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Preface 



The 'Occam 2 toolset user manuat is a combined user and reference guide to 
the Occam 2 toolset. 

Part 2 'Occam libraries and appendices^ (this book) provides a detailed descrip- 
tion ot all the libraries supplied with the toolset. Technical reference data Is given 
in the appendices at the end of this book which also includes a glossary of terms 
and a short bibliography, 

A description of the toolset and how it is used to develop and run transputer 
programs is given in Part 1 'User guide and tools' (72 TDS 275 02). 

References which span the two parts, take the form of a part number followed 
by a chapter or section number. Each part contains its own index. 

This manual does not contain details of how to install the software, which is to 
be found in the Delivery Manual that accompanies the shipment. 

Host versions 

The manuai is designed to cover all host versions of the toolset: 

IMS D7205 - IBM and NEC PC running MS-DOS. 

IMS D5205 - Sun 3 systems running SunOS 

IMS D4205 - Sun 4 systems njnnlng SunOS 

IMS D6205 - VAX systems running VMS 
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Conventions used in the manual 

Convention Description 

HaJics Used in command line syntax to denote parameters for which 

values must be supplied. Also used for book titles and for 
enfiphasis. 

Bold Used for new terms, pin signals, and the text of error mes- 

sages. 



Teletype Used for listings of program exannples and to denote user 
input and terminal output. 



iEY| Used to denote function keys for the debugger and simulator 

tools. Keyboard layouts for specific terminals can be found in 
the Delivery Manual that accompanies the shipment. 



□ Used to indicate the continuation of a function key description. 

Braces Used to denote lists of items in command Itn© syntax. 

{} 

Brackets Used to denote optional items in command line syntax. 

n 



Option prefix Examples of command line input are duplicated to show both 
option prefix characters. Use the line containing the V char- 
acter if you have an MS-DOS or VMS based system and the 
line containing the -' character if you are using any other host 
including UNIX. 
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1 The Occam libraries 



1.1 Introduction 

A comprehensive set of OCCam libraries is provided for use with the toofset. 
They include the compiler libraries whicii are automatically referenced by the 
compiler, and a number of user libraries to assist with common programming 
tasks. 

The user libraries provide standard mathematical functions, host i/o and file man- 
agement procedures, file stream i/o support, and many other functions. A full list 
of all the toolset libraries with brief descriptions of their contents can be found in 
table 1.1. 



Library 


Description 




Multiple length Integer arithmetic 




Floating point functions 


Compiler 


32 bit IEEE arithmetic functions 


Libraries 


64 bit IEEE arithmetic functions 




2D block move library 




Bit manipulation and CRC library 




Arithmetic instruction library 


snglmath.lib 


Single length mathematical functions 


dblmath.lib 


Double length mathematical functions 


tbmaths,lib 


T4 series optimised maths functions 


hostio. lib 


Host file server library 


streamio , lib 


Stream i/o library 


string. lib 


String library 


convert .lib 


Type conversion library 


crc.lib 


Block CRC library 


xlink.lib 


Extraordinary link handling library 


debug. lib 


Debugging support functions 


callc.lib 


Mixed languages support library 


msdos . lib 


DOS specific hostio library 



Table 1.1 Toolset libraries 
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1.1.1 Using the OCCam libraries 

If a library routine is used in a program then the library must be declared with 
the #DSE directive and the declaration must be in scope where the routine is 
used. The scope of a library, as with all Occam declarations, is determined by 
its level of indentation In the Occam text. 

An example showing how to declare a library is given below. 

#USE "hostio.lib" 

Linking libraries 

Ail libraries used by a program or program module must also be linked with 
the main progam. This includes the compiler libraries even though they are 
automatically referenced when the program is complJed, 

1.1.2 Listing library contents 

You can use the iiist tool to examine the contents of a library and determine 
which routines are available. The tool displays procedural interfaces for routines 
in each library module and the code size and workspace requirements for indi- 
vidual modules. It can also be used to determine the transputer types and error 
modes for which the code was compiled. (See chapter 20 for details of ilist). 



1.1.3 Toolset constants 

Constants and protocols used by the toolset libraries are defined in six include 
files which are supplied with the toolset. Two of the six files provide constants 
and definitions for the hostio and streamio libraries, a third provides mathematical 
and trigonometric constants, the fourth contains the absolute transputer link ad- 
dresses, the fifth contains the rates at which the two transputer clocks increment 
on the transputer and the sixth provides constants to support the DOS specific 
library routines. AIJ files containing constant definitions must be declared in the 
program before the library that references them. 

Files of constants provided with the tooEset are summarised in table 1.2. Full 
listings of the files can be found in appendix C. 
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File 


Description 


hostio.inc 
streamio , inc 
mathvals .inc 
linkaddr .inc 
ticks ,inc 
msdos . inc 


Constants for the host file server interface 
Constants for the stream i/o interfaces 
Maths constants 
Addresses of transputer [inks 
Rates of the two transputer clocl^s 
DOS specific constants 



Table 1.2 Files of constants 

1.2 Compiler libraries 

Compiler libraries are used internally by the compiler to implement muitipie length 
and floating point arithmetic, IEEE functions, and special transputer functions 
such as bit manipulation and 2D block data moves. They are found automatically 
by the compiler on the path specified by the ISEARCH host environment variable 
and do not need to be referenced by the #uSe directive. 

The compiler library virtual , lib, is disabled (i.e, automatic searching of the 
library by the compiler can be suppressed) by using the compiler *Y" option. The 
other compiler libraries are disabled by using the compiler 'E' option. 

Separate libraries are supplied tor the folEowing processor types; 

• T2 family 

• T8 family 

• 32-bit processors 

All error modes are supported by each library. 
A full list of the compiler libraries is given below: 



File 


Processors 


occam2 . lib 
occama , lib 
occamd .lib 
occamutl.lib 
virtual. lib 


T212/T222n"225/M212 

T400/T414/T425/TAyTB 

T800n-80in-805 

All 

All 



The compiter library occamutl. lib contains routines which are called fnam 
within some of the other compiler libraries and virtual . lib is used to support 
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interactive debugging. These two [ibraries support all processor types and error 
modes. 

File names of the compiler libraries must not be changed. The compiler as- 
sumes these filenames, and generates an error if they are not found on the path 
specified by the host environment variable isearch. 

Descriptions of some of the compiler library functions and procedures can be 
found in the 'OCCam 2 Reference Manual'. 



1.2.1 User functions and procedures 

The following routines from the compiler libraries may be of interest to the ap- 
plications programmer. Calls to these routines can be made directly and do 
not have to reference the library in a #USE statement, provided the compiler 'e' 
option is not used. 

The functions are grouped as follows: maths functions, including some IEEE and 
extended arithmetic routines; 2-D block moves; bit manipulation; functions tor 
cyclic redundancy checking (CRC) and supplementary arithmetic support func- 
tions. 

The procedures listed in this section are grouped as follows: dynamic code 
loading support; rescheduling process priority queue and procedures to set the 
transputer error flag. 

It is worth noting the difference between the default Occam behaviour of arith- 
metic operations and the behaviour of the equivalent IEEE arithmetic functions. 
The difference in the implementations concerns the treatment of NaNs ('Not a 
Number') and infs ('± Infinity'), The default OCCam behaviour of arithmetic 
operations is to cause an error if such quantities occur, whereas the IEEE func- 
tions implement the ANSI/IEEE 754-1985 standard. The IEEE functions use of 
infinities and NaKs to handle errors and overflows may be prefered in some in- 
stances, in which case these functions must be explicitly called. For example If 
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A, B and C are REAL325: 

A := B + C — default occam behaviour, 

A := REAL320P(B, 0, C) — IEEE function, round to 

— nearest only. The 

— indicates a ^+' 

— operation, 

A := IEEE320P(B^ 1, 0, C) — IEEE function with 

— rounding option. The 

— 1 indicates round to 

— nearest. The 

— indicates a ^+' 
-- operation. 

The IEEE tloaJing point arithmetic functions are described in more detail in the 
'Occam 2 Reference Manual', 
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Maths functions 



Result(s) 


Function Parameter specifiers 


REALS 2 


ABS 


VAL REAL32 x 






REAL32 


SQRT 


VAL REAL32 x 






REAL32 


LOGB 


VAL REAL32 x 






IHT, 
REAL32 


FLOAT ING . UNPACK 


VAL REAL32 x 






REAL32 


MINUSX 


VAL REAL32 x 






REAL32 


MaLBY2 


VAL REAL32 x 






REAL32 


DIVBy2 


VAL REAL32 x 






REAL32 


FPINT 


VAL REAL32 x 






BOOL 


ISNAN 


VAL REAL32 x 






BOOL 


NOTFINITE 


VAL REAL32 x 






REAL32 


SCAT.KB 


VAL REAL32 x. 


VAL INT 


n 


REAL32 


COPYSIGN 


VAL REAL32 x, 


y 




REAL32 


NEXTAFTER 


VAL REAL32 x, 


y 




BOOL 


ORDERED 


VAL REAL32 x, 


y 




BOOL, 

1NT32, 

REAL32 


ARGUMENT . FKPUCE 


VAL REAL32 x, 


y/ y.err 


REAL32 


REAL320P 


VAL REAL32 x, 
VAL REAL32 y 


VAL INT 


Opr 


REAL32 


REAL32REM 


VAL REAL32 x. 


y 




BOOL, 
REAL32 


IEEE320P 


VAL REAL32 x, 
VAL INT rm, op, 
VAL REAL32 y 




BOOL, 
REAL32 


IEEE32REM 


VAL REAL32 x. 


y 




BOOL 


REAL32EQ 


VAL REAL? 2 x, 


y 




BOOL 


REAL32GT 


VAL REAL32 x, 


y 




INT 


lEEECOMPARE 


VAL REAL32 x. 


y 
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Result(s) 


Function 


Parameter specifiers 


REAL64 


DABS 


VAL REAL64 


X 






REAL64 


DSQRT 


VAL REAL€4 


X 






REAL64 


DLOGB 


VAL REAL64 


X 






INT, 


DFLOATING . UNPACK 


VAL REAL64 


X 






REAL64 












REAL64 


DMINDSX 


VAL REAL64 


X 






REAL64 


DMULBY2 


VAL REAL64 


X 






REAL64 


DDIVBY2 


VAL REAL64 


X 






REAL64 


DFPINT 


VAL REAL64 


X 






BOOL 


DISNAN 


VAL REAL64 


X 






BOOL 


DNOTFINITE 


VAL REAL64 


X 






PEAL64 


DSCAT.EB 


VAL REAL64 


X, 


VAL INT 


n 


ke:al64 


DCOPYSIGN 


VAL REAL64 


X/ 


y 




REAL64 


DNEXTAFTER 


VAL REAL64 


X, 


y 




BOOL 


DORDERED 


VAL REAL64 


Xf 


y 




BOOL, 


DARGUMENT . REDUCE 


VAL REAL64 


X/ 


y, y^err \ 


INT32, 












REAL64 












REAL64 


REAL640P 


VAL REAL64 
VAL REAL64 


y 


VAL INT 


op, 


REAL64 


REAL64REM 


VAL REAL64 


X, 


y 




BOOL, 


IEEE640P 


VAL REAL64 


X, 






REAL64 




VAL INT rm, 


op, 








VAL REAL64 


y 






BOOL, 


IEEE64REM 


VAL REAL64 


X, 


y 




REAL64 












BOOL 


REAL64EQ 


VAL REAL64 


X, 


y 




BOOL 


REAL64GT 


VAL REAL64 


X, 


y 




INT 


DIEEECOMPARE 


VAL REAL64 


Xr 


y 
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Resu)t(s) 


Function 


Parameter specifiers 


INT 


LONGADD 


VAL INT left, right, 
carry . in 


INT 


LONGSUM 


VAL INT left, right, 
carry . in 


INT 


LONGSUB 


VAL INT left, right, 
borrow, in 


INT, INT 


LONGDIFF 


VAL INT left, right, 

borrow, in 


INT, INT 


LONGPROD 


VAL INT left, right, 
carry . in 


INT, INT 


LONGDIV 


VAL INT dividend. hi, 
dividend , lo , divisor 


INT, INT 


SHXFTRIGHT 


VAL INT hi. in, lo.in, 
places 


INT, INT 


SHIFTT.FFT 


VAL INT hi. in, lo.in, 
places 


INT, INT, INT 


NORMALISE 


VAL INT hi. in, lo.in 


INT 


ASHIFTRIGHT 


VAL INT argument, places 


INT 


ASHIPTLEFT 


VAL INT argument, places 


INT 


ROTATET.FFT 


VAL INT argument, places 


INT 


ROTATERIGHT 


VAL INT argument, places 



SHIFTRIGHT and SHIFTLEFT return zeroes when the number of places to 
shift is negative, or is greater than twice the transputer's word length. In this 
case they may lake a long time to execute. 

ASHIFTRIGHT, ASHIFTLEFT, ROTATERIGHT and ROTATELEFT are all in- 
valid when the number of places to shift is negative or exceeds the transputer's 
word length. 
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2D blocl< moves 



Procedure 



M0VE2D 



DRAW2D 



CLIP2D 



Parameter Specifiers 



VAL [] []BYTE Source, 

VAL INT sx, sy, [1[]BYTE Dest, 

VAL INT dx, dy, width, length 

VAL [] []BYTE Source, 

VAXi INT sxr SYr [][]BYTE Dest, 

VAL INT dx, dy, width, length 

VAL [] [IBYTE Source, 

VAL INT sx, sy, [] []BYTE Dest, 

VAL INT dx, dy, width, length 



Procedure definitions 

M0VE2D 

PROC M0VE2D (VAL [] []BYTE Source, 

VAL INT sx, sy, [] [ ] BYTE Dest, 
VAL INT dx, dy, width, length) 

l^yioves a data block of size width by length starting at byte 
Source [sy] [s3c] to the block starting at Dest [dy] [dx] . 

DRAW2D 

PROC DRAM2D (VAL [][]BYTE Source, 

VAL INT sx, sy, [] []BYTE Dest, 
VAL INT dx, dy, width, length) 

As M0VE2D but only non-zero bytes are transferred. 

CLIP 2D 

PROC CLIP2D (VAL []t]BYTE Source, 

VAL INT sx, sy, [] [IBYTE Dest, 
VAL INT dx, dy, width, length) 

As M0VE2D but only zero bytes are transferred. 
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Bit manipulation functions 



Result 


Function 


Parameter Specifiers 


INT 


BITCODNT 


VAL INT Word, Countin 


INT 


BITREVNBITS 


VAL INT X, n 


INT 


BITREVWORD 


VAL INT X 



J 



Function definitions 

BITCOUNT 

INT FUNCTION BITCOUNT (VAL INT Word, Count In) 

Counts the number of bits set to \ in Word, adds it to Countin, and 
returns the total. 

BITREVNBITS 

INT FUNCTION BITREVNBITS (VAL IKT ac, n) 

Returns an int containing the n least significant bits of x in reverse 
order. The upper bits are set to zero. Tine operation is invalid if n is 
negative or greater than the number of bits in a word. 

BITREVWORD 

INT FUNCTION BITREVWORD (VAL INT x) 

Returns an INT containing the bit reversal of x. 
CRC functions 



Result 



INT 



INT 



Function 



CRCWORD 



CRCBYTE 



Parameter Specifiers 



VAL INT data, CRCin, 
generator 

VAL INT data, CRCIn, 
generator 
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CRCWORD 



INT FUNCTION CRCWORD 



(VAi INT data, 
generator) 



CRCIn, 



Performs a cyclic redundancy check over the single word data using 
the ORG value obtained from the previous call, generator is the CRC 
polynomial generator. Can be used iteratively on a sequence of words 
to obtain the CRC. 



CRCBYTE 



INT FUNCTION CRCBYTE (VAL INT data, 

generator) 



CRCIn, 



As CRCWORD but perforn^s the check over a single byte. The byte pro- 
cessed is contained in the most significant byte of the word data. 

For further information about CRC functions see 'JNMOS Technical note 
26: Notes on graphics support and performance improvements on the 
IMS T800'. 

Supplementary arithmetic support functions 



Result(s} 


Function 


Parameter specifiers 


INT 


FRACMUL 


VAL INT X, y 


INT, 


UNPACK SN 


VAL INT X 


INT, 






INT 






INT 


ROUND SN 


VAL INT Yexp, Yfrac, 
Yguard 



Function descriptions 

FRACMUL 

INT FUNCTION FRACMUL (VAL INT x, y) 

Performs a fixed point multiplication of x and y, treating each as a binary 
fraction in the range [-1, 1), and returning their product rounded to the 
nearest available representation. The value of the fractions represented 
by the arguments and result can be obtained by muSttpJying their INT 
value by 2~^^ (on a 32-bit processor) or 2"^^ (on a 16-bit processor). 



72 IDS 276 02 



March 1991 



14 



The Occam libraries 



The result can overflow if both x and y are -1. 

This routine is compiled inline into a sequence of transputer instructions 
on 32-bit processors, or as a call to a standard library routine for 16-bit 
processors. 



DNPACKSN 



INT, INT, INT FUNCTION UNPACKSN (VAL INT x) 

This returns three parameters; from left to right they are Xf rac, xexp, 
and Type. X is regarded as an IEEE single length real number (i.e. a 
RETYPED REAL32). The function unpacks X into Xexp, the (biased) 
exponent, and Xf rac the fractional part, with implicit bit restored. It also 
returns an integer defining the Type of X. ignonng the sign bit: 



Type 



Reason 



X is zero 

X is a normalised or denormalised number 

X is Inf 
X is NaN 



This routine is compiled inline into a sequence of transputer instructions 
on 32-bit processors such as the IMS T425, which do not have afloating 
support unit, but do have special instructions for floating point operations, 
For other 32-bit processors the function ts compiled as a call to a standard 
library routine. It is invalid on 16-bit processors, since Xf rac cannot fit 
into an int. 



ROUNDSN 



INT FUNCTION ROUNDSN 



(VAL INT Yexp, Yfrac, 
Yguard) 



This takes a possibly unnormalised fraction, guard word and exponent, 
and returns the IEEE floating point value it represents. It takes care 
of all the normalisation, post-normalisation, rounding and packing of the 
result. The rounding mode used is round to nearest. The exponent 
should already be biased. 

The function normalises and post-normalises the number represented 
by Yexp, Yf rac and Yguard into local variables Xexp, Xf rac, and 
Xgaurd. It then packs the (biased) exponent Xexp and fraction xf rac 
into the result, rounding using the extra bits in Xguard. The sign bit is 
set to 0. If overfow occurs, inf is returned. 
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This routine is compiled inline into a sequence of transputer instructions 
on 32-bit processors sucii as the IMS T425, which do not have afloating 
support unit, but do have special instructions for floating point operations. 
For other 32-bit processors the function is compiled as a call to a standard 
library routine. It is invalid on 16-bit processors, since Xf rac cannot fit 
into an int. 



Dynamic code loading support procedures 



Procedure 


Parameter Specifiers 


KERNEL. RUN 


VAL []BYTE code, 
VAL INT entry. offset, 
[]INT workspace, 
VAL INT 
no . of . parameters 


LOAD . INPUT . CHANNEL 


INT here, 

CHAN OF ANY in 


LOAD . INPUT . CHANNEL . VECTOR 


INT here, 

nCHAN OF ANY in 


LOAD . OUTPUT , CHANNEL 


INT here, 

CHAN OF ANY out 


LOAD , OUTPUT . CHANNEL . VECTOR 


INT here, 

[]CHAN OF ANY out 


LOAD ■ BYTE . VECTOR 


INT here, 

VAL []BYTE bytes 



Procedure definitions 



KERNEL. RUN 



PROC KERNEL. RUN (VAL [ ] BYTE code, 

VAL INT entry. offset, 
[]INT workspace, 
VAL INT no, of -parameters) 

The effect of this procedure is to cail the procedure loaded in the code 
buffer, starting execution at the location code [entry .offset] . 

The code to be called must begin at a word-aligned address. To ensure 
proper alignment either start the array at zero or realign the code on a 
word boundary before passing it into the procedure. 
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The workspace buffer Js used to hold the focal data of the called pro- 
cedure. The required size of this buffer and the code buffer must be 
derived from information in the code file. 

The parameters passed to the called procedure should be placed at the 
top of the workspace buffer by the calling procedure before the call of 
KERNEL. RUN. The call to KERNEL. RUN returns when the called pro- 
cedure terminates. If the called procedure requires a separate vector 
space, then another buffer of the required size must be declared, and its 
address placed as the last parameter at the top of workspace. As calls 
of KERNEL. RON are handled specially by the compiler it is necessary 
for no. of .parameters to be a constant known at compile time and 
to have a value > 3. 

The workspace passed to kernel. run must be at least: 

[ws. requirement + no. of .parameters + 2] INT 

where ws . requirement is the size of workspace required, determined 
when the called procedure was compiled, and stored in the code file and 
no . of . parameters includes the vector space pointer if it is required. 

The parameters must be loaded before the call of kernel. run. The 
parameter corresponding to the first formal parameter of the procedure 
should be in the word adjacent to the saved iptr word, and the vector 
space pointer or the last parameter should be adjacent to the top of 
workspace where the wptr word will be saved. 

Note: code developed with the current toolset will not be able to call 
code compiled by previous toolsets, if channel arrays are used. 

LOAD . INPUT . CHANNEL 

LOAD. INPUT, CHANNEL (INT here, CHAN OF ANY in) 

The variable here is assigned the address of the input channel in, 

LOAD . INPUT , CHANNEL .VECTOR 

LOAD. INPUT. CHANNEL. VECTOR (INT here, 

[]CHAN OF ANY in) 

The variable here is assigned the address of the base element of the 
channel array in (i.e, the base of the array of pointers). Note this is a 
change from the previous implementation of this procedure which used 
to return the actual address of the input channel array. 
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LOAD . OUTPUT . CHANNEL 

LOAD. OUTPUT. CHANNEL (INT here, CHAN OF ANY out) 

The variable here is assigned the address of the output channel out, 

LOAD , OUTPUT . CHANNEL , VECTOR 

LOAD. OUTPUT. CHANNEL. VECTOR (INT here, 

[]CHAN OP ANY out) 

The variable here is assigned the address of the b^e element of the 
channel array out (i.e. the base of the array of pointers). Note this is a 
change from the previous implementation of this procedure which used 
to return the actual address of the output channel array. 

LOAD , BYTE . VECTOR 

LOAD. BYTE. VECTOR (INT here, VAL []BYTE bytes) 
The variable here is assigned the address of the byte array bytes. 

Transputer error flag manipulation 



Procedure 


Paranneter Specifiers 


CAUSEERROR 
ASSERT 




VAL BOOL test 



Procedure definitions 

CAUSEERROR 

CAUSEERROR () 

Inserts a seterr instruction into the program. If the program is in STOP 
or UNIVERSAL mode it inserts a stopp instruction as well. The error is 
then treated in exactly the same way as any other error would be treated 
in the error mode in which the program is compiled. For example, in 
HALT mode the whole processor will halt. 
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ASSERT 

PROC ASSERT (VAL BOOL test) 

Ai compile time the compiler will check the value o* test and if it is 
FALSE the compiler will give a compile time error; if it is true, the 
compiler does nothing. If test cannot be checked at compile-time then 
the compiler will insert a run-time check to detect its status. 

ASSERT is a useful routine for debugging purposes. Once a program is 
working correctfy the compiler option 'na' can be used to prevent code 
being generated to check for asserts at run-time. If possible asserts 
will still be checked at compile time. 

Rescheduling priority process queue 



Procedure 


Parameter Specifiers 


RESCHEDULE 






Procedure definition 

RESCHEDULE 

RESCHEDULE () 

Inserts enough instructions into the program to cause the current process 
to be moved to the end of the current priority scheduling queue, even if 
the current process is a 'high priority' process. 
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1.3 Maths libraries 

Elementary maths and trigonometric functions are provided in three libraries, as 

follows: 



Library 


Description 


snglmath. lib 

dblmath.lib 
tbmaths.lib 


Single length library 
Double lenglh library 
TB optimised library 



The single and double length libraries contain the same set of functions in single 
and double length forms. By convention the double length forms begin with the 
letter 'D'. Function names are in upper case. 

The TB optimised library is a combined single and double length library con- 
taining ali the single and double length functions optimised for the T400, T414 
and T425 processors. The standard maths libraries can also be used on the 
T400, T414 and T425. but optimum perfornnance on these processors can be 
achieved by using the optimised functions. 

The accuracy of the T400/T414/T425 optimised functions is similar to that of 
the standard single length functions but results returned may not be identical 
because different algorithms are used. 

Functions in the optimised library have the same names as the equivalent func- 
tions in the single and double length libraries. This means that the optinnised 
library cannot be used together with either the single or double length library on 
the same processor If the optimised library is used in code compiled for any 
processor except a T4 00, T414 or T425, the compiler reports an error. 

A set of constants for the maths libraries are provided in the include file 
mathvals.inc, which is listed in appendix C. 



1.3.1 Introduction 

This, and the following subsections, contain some notes on the presentation of 
the elementary function libraries described in section 1.3.2, and the TB version 
described in section 1.3.3. 

These function subroutines have been written to be compatible with the ANSI 
standard for binary floating-point arithmetic (ANSMEEE std 754-1985). as im- 
plemented in Occam. They are based on the algorithms in: 
Cody, W. J., and Waite, W. M. [1930]. Software Manual for the Elementary 
Functions. Prentice-Hall. New Jersey. 
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The only exceptions are the pseudo-random number generators, which are 
based on algorithms in: 

Knuth, D. E. [1981]. The Art of Computer Programming, 2nd. edition, Volume 
2: Seminumericaf Algorithms, Addison-Wesley, Reading. Mass. 

Inputs 

All the functions In the library (except ran and dran) are called with one or two 
parameters which are binary lloating-point numbers in one of the IEEE standard 
formats, either 'single-length' (32 bits) or 'double-length' (64 bits). The parame- 
ter(s) and the function result are of the same type. 

NaNs and Infs 

The functions will accept any value, as specified by the standard, including spe- 
cial values representing NaNs ('Not a Number') and Infs ('Infinity'), NaNs are 
copied to the result, whilst Infs may or may not be in the domain. The do- 
main is the set of arguments for which the result is a normal (or denormalised) 
floating-point number. 

Outputs 

Exceptions 

Arguments outside the domain [apart from NaNs which are simply copied through) 
give rise to exceptional results, which may be NaN, -nlnf, or ^Inf. Infs mean 
that the result is mathematically well-defined but loo large to be represented in 
the floating-point format. 

Error conditions are reported by means of three distinct NaNs: 
undefined.NaN 

This means that the function is mathematically undefined for this argument, for 
example ihe logarithm of a negative number. 

unstable.NaN 

This means that a small change in the argument would cause a large change 
in the value of the function, so any error in the input will render the output 
meaningless. 
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inexact.NaN 

This means that although the mathematical Junction is well-defined, its value is 
in range, and it is stable with respect to input errors at this argument, the limi- 
tations of word-length (and reasonable cost of the algorithm) make it impossible 
to compute the correct value. 

The impiementations will return the following values for these Not-a-Numbers: 



Error 


Single length value 


Double length value 


undefined, NaN 
unstable. NaN 
inexact.NaN 


#7F80001 
#7F800008 
#7F800004 


#7FF00002 00000000 
#7FF00001 00000000 
#7FF00000 80000000 



Accuracy 

Range Reduction 

Since it is impractical to use rational approximations (i.e, quotients of polynomi- 
als) which are accurate over large domains, nearly all the subroutines use math- 
ematical identities to relate the function value to one computed from a smaller 
argument, taken from the 'primary domain', which is small enough for such an 
approximation to be used. This process is called 'range reduction' and is per- 
formed for all arguments except those which already lie in the primary domain. 

For most of the functions the quoted error Is for arguments in the primary domain, 
which represents the basic accuracy of the approximation. For some functions 
the process of range reduction results in a higher accuracy for arguments outside 
the primary domain, and for others it does the reverse. Refer to the notes on 
each function for more details. 

Generated Error 



If the true value of the function Is large the difference between it and the com- 
puted value (the 'absolute error') is likely to be large also because of the limited 
accuracy of floating-point numbers. Conversely if the true value is small, even a 
small absolute error represents a large proportional change. For this reason the 
error relative to the tnje value is usually a better measure of the accuracy of a 
floating-point function, except when the ouput range is strictly bounded. 

If / is the mathematical function and F the subroutine approximation, then the 
relative error at the floating-point number X {provided f(X) is not zero) is; 



RE{X) = 



{F{X)-f{X)) 

fix) 
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Obviously the relative error may becorne very large near a zero of f{X). If the 
zero is at an irrational argument (which cannot be represented as a floating-point 
value), the absolute error is a better measure of the accuracy of the function near 
the zero. 

As it is impractical to find the relative error for every possible argument, statistical 
measures of the overalJ error must be used. If the relative error is sampled at a 
number of points Xn{n^^ to N), then useful statistics are the maximum relative 
error and the root-mean-square relative error. 

MRE^ max \RE(X^)\ 



RMS RE ■■ 



\ 



^{RE{Xr.)f 



Corresponding statistics can be formed for the absolute error also, and are called 
MAE and RMSAE respectively. 

The MRE generally occurs near a zero of the function, especially If the true zero 
is irrational, or near a singularity where the result is large, since the 'granularity' 
of the floating-point numbers then becomes significant. 

A useful unit of relative error is the relative magnitude of the least significant 
bit in the floating-point fraction, which is called one *unit in the last place' (ulp), 
{i.e- the smallest e such that 1 +£ 7^ 1). Its magnitude depends on the floating- 
point format: for single-length it is 2"^^ = 1.19 + 10"^ and for double-length it Is 
2-52^2.22 + 10-^^. 

Propagated Error 

Because of the limited accuracy of floating-point numbers the result of any cal- 
culation usually differs from the exact value. In effect, a small error has been 
added to the exact result, and any subsequent calculations will inevitably involve 
this error term. Thus it is important to determine how each function responds to 
errors In its argument. Provided the error is not too large, it is sufficient just to 
consider the first derivative of the function (written /'). 

if the relative error in the argument X\sd (typically a few ulp), then the absolute 
error (E) and relative error (e) in f(X) are: 

E^\xr(X)d\=Ad 
\Xf[X)d 



= Rd 



I f[X} 

This defines the absolute and relative error magnification factors A and R. When 
both are large the function is unstable, i.e. even a small error in the argument, 
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such as would be produced by evaluating a floating-point expression, will cause 
a large error in the value of the function. The functions return an unstable.NaN 
in such cases which are sinnple to detect. 

The functional forms of both A and R are given in the specification of each 
function. 

Test Procedures 

For each function, the generated error was checked at a large number of argu- 
ments (typically 100000) drawn at random from the appropriate domain. First 
the double-length functions were tested against a 'quadruple-length' implemen- 
tation (constructed for accuracy rather than speed), and then the single-length 
functions were tested against the double-length versions. 

in both cases the higher-precision implementation was used to approximate the 
mathematical function (called / above) in the computation of the error, which 
was evaluated in the higher precision to avoid rounding errors. Error statistics 
were produced according to the formulae above. 

Symmetry 

The subroutines were designed to refiect the mathematical properties of the 
functions as much as possible. For all the functions which are even, the sign 
is removed from the input at the beginning of the computation so that the sign- 
symmetry of the function is always preserved. For odd functions, either the 
sign is removed at the start and then the appropriate sign set at the end of 
the computation, or else the sign is simply propagated through an odd degree 
polynomiai. In many cases other symmetries are used in the range-reduction, 
with the result that they will be satisfied automatically. 

The Function Specifications 

Names and Parameters 

All single length functions except ran return a single result of type REAL32, 
and a!l except ran, power and atan2 have one parameter, a val real32 
for the argument of the function. 

POWER and atan2 have two parameters which are val real32s for the two 
arguments of each function. 

ran returns two results of type reals 2 , int32 , and has one parameter which 

is a VAL INT32. 
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In each case the double-length version of name is called Dname, returns a 
REAL64 (except DRAN, which returns REAL64, INT64), and has parameters 

of type VAL REAL64 (VAIi INT64 for DRAN). 

Terms used in the Specifications 

A and R Multiplying factors relatir^g the absolute and relative errors in the output 

to the relative error in the argument. 

Exceptions Outputs tor invalid inputs (i.e. those outside the domain), other 
than NaN (NaNs are copied directly to the output and are not listed as 
exceptions). These are ali Infs or NaNs. 

Generated Error The difference between tlie true and computed values of the 
function, when the argument is error-free. This is measured statistically 
and displayed for one or two ranges of arguments, the first of which is 
usually the primary domain (see below). The second range, if present, 
is chosen to illustrate the typical behaviour of the function. 

Domain The range of vaild inputs, i.e. those for which the output is a normal or 
denormal floating-point number. 

MAE and RMSAE The Maximum Absolute Error and Root-Mean-Square abso- 
lute error taken over a number of arguments drawn at random from the 
indicated range. 

WIRE and RMSRE The Maximum Relative Error and Root-Mean-Square rela- 
tive error taken over a number of arguments drawn at random from the 
indicated range. 

Range The range of outputs produced by all arguments in the Domain. The 
given endpoints are not exceeded. 

Primary Domain The range of arguments for which the result is computed using 
only a single rational approximation to the function. There is no argument 
reduction in this range. 

Propagated Error The absolute and relative error In the function value, given a 
small relative error in the argument. 

ulp The unit of relative error is the 'unit in the iast place' (ulp). This is the 
relative magnitude of the least significant bit of the floating-point fraction 
(i.e. the smallest e such that 1 +c^^). 
N.B. this depends on the floating-point format. 
For the standard single-length format it is 2~^ = 1,19* 10"^. 
For the double-length format it is 2"^^ = 2.22 * 10"'^, 
This is also used as a measure of absolute error, since such errors can 
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be considered 'relative' to unity. 

Specification of Ranges 

Ranges are given as intervals, using the convention tiiat a square bracket '[* or 
']' means that liie adjacent endpoint is included in the range, whilst a round 
bracket '{' or J means that It Is excluded. Endpoints are given to a few 
significant figures only. 

Where the range depends on the floating-point format, single-length is Indicated 
with an S and double-length with a D. 

For functions with two arguments the complete range of both arguments is given. 
This means that for each number in one range, there is at least one (though 
sometimes only one) number in the other range such that the pair of arguments 
is valid. Both ranges are shown, linked by an Y. 

Abbreviations 

In the specifications, XMAX is the largest representable floating-point number: 
in single-length it is approximately 3.4* 10^^, and in double-length It Is approxi- 
mately 1.8* 10^^^ 

Pi means the closest floating-point representation of the transcendental number 
TT. ln{2) the closest representation of log^(2), and so on. 

In describing the algorithms, 'X' is used generically to designate the argument, 
and 'result' (or RESULT, in the style of OCCam functions) to designate the output. 

1.3.2 Single length and double length elementary function libraries 

The versions of the libraries described by this section have been written using 
only floating-point arithmetic and pre-defined functions supported in occam. 
Thus they can be compiled for any processor with a full implementation of Oc- 
cam, and give identical results. 

These two libraries will be efficient on processors with fast lloating-potnt arith- 
metic and good support for the floating-point predefined functions such as 
MUI1BY2 and ARGUMENT, REDUCE. For 32-bit processors without special hard- 
ware for floating-point calculations the alternative optimised library described in 
section 1.3.3 using fixed-point arithmetic will be faster, but will not give identical 
results. 

A special version has been produced for 16-bit transputers, which avoids the 
use of any double-precision arithmetic In the single precision functions. This is 
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distinguished in the notes by the annotation 'T2 special'; notes relating to the 
version forTS and TB are denoted by 'standard'. 

Single and double length maths functions are listed below. Descriptions of the 
functions can be found in succeeding sections. 

To use the single length library a program header must include the line 

#USE "snglmath.lib" 
To use the double length library a program header must include the line 

#USK "dblmath.lib" 



Result(s) 


Function 


Parameter specifiers 


REAL32 


ALOG 


VAL REAL32 X 






REAL32 


ALOGIO 


VAL REAL32 X 






REAL32 


EXP 


VAL REAL32 X 






REAL32 


POWER 


VAL REAL32 X, 


VAL REAL32 


y 


REAL32 


SIN 


VAL REAL32 X 






REAL32 


COS 


VAL REAL32 X 






REAL32 


TAN 


VAL REAL32 X 






REAL32 


ASIN 


VAL REAL32 X 






REAL32 


ACOS 


VAL REAL32 X 






REAL32 


ATAN 


VAL REAL32 X 






REAL32 


ATAN2 


VAL REAL32 X, 


VAL REAL32 


y 


REAL32 


SINE 


VAL REAL32 X 






REAL32 


COSH 


VAL REAL32 X 






REAIi32 


TANH 


VAL REAL32 X 






REAI.32,INT32 


RAN 


VAL IKT32 X 
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Resu]t(s) 


Function 


Parameter specifiers 


REAI.64 


DTtLOG 


VAL REAL64 X 




REAL64 


DALOGIO 


VAL REAL64 X 




re:al64 


DEXP 


VAL REAL64 X 




REAL64 


DPOWER 


VAL REAL64 X, VAL REAL64 


Y 


REAI.64 


DSIN 


VAL REAL64 X 




REAL64 


DCOS 


VAL REAL64 X 




REAL64 


DTAN 


VAL REAL64 X 




REAL64 


DAS IN 


VAL REAL64 X 




R£AX^64 


DACOS 


VAL REAL64 X 




REAL64 


DATAN 


VAL REAL64 X 




REAL64 


DATAN2 


VAL REAL64 X, VAL REAL64 


Y 


REAL64 


DSINH 


VAL REAL64 X 




REAL64 


DCOSH 


VAL REAL64 X 




REAL64 


DTANH 


VAL REAL64 X 




REAL64,INT64 


DRAN 


VAL INT 64 X 
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Function definitions 

ALOG 

DALOG 

REAL32 FUNCTION ALOG (VAL REAL32 X) 
REAL64 FUNCTION DALOG (VAL REAL64 X) 

Compute log,(X). 

Domain: (O.XMAX] 

Range: [MinLog.MaxLog] (See note 2) 

Primary Domain: [n/5/2, V2) = [0.7071, 1.4142) 

Exceptions 

All arguments outside the domain generate an undefined. NaN. 

Propagated Error 

^^1. H=1/log,(Ar) 

Generated Error 

Primary Domain Error: MRE RIVISRE 

Single Length(Standard): 1.7 ulp 0.43 ulp 

Single Length(T2 special): 1.6 ulp 0.42 ulp 

Double Length: 1.4 ulp 0.38 uip 

The Algorithm 

1 Split X into its exponent N and fraction F. 

2 Find LnF, the natural iog of F, with a floating-point rational ap- 
proximation. 

3 Compute ln(2) * A^ with extended precision and add it to LnF to 
get the result. 

Notes 

1) The term ln(2) * N is much easier to compute (and more accurate) 
than LnF, and it is larger provided N is not (i.e. for arguments outside 
the primary domain). Thus the accuracy of the result improves as the 
modulus of log(X) increases. 
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2) The minimum value that can be produced, MinLog, is the logarithm 
of the smallest denormalised floating-point number. For single length 
Minlog is -103.28, and for double length it is -745.2, The maximum 
value MaxLog is the logarithm of XMAX. For single-length it is 88.72, 
and for doubte-Iength it is 709.78. 

3) Since Inf is used to represent a// values greater than XMAX its log- 
arithm cannot be defined. 

4) This function is well-behaved and does not seriously magnify errors in 
the argument. 

ALOGIO 
DALOGIO 

REAL32 FUNCTION ALOGIO (VAL REAL32 X) 
REAL64 FUNCTION DALOGIO (VAL REAL64 X) 

Compute logioiX). 

Domain: {0,XMAX\ 

Range: [M%nL^Q,MaxL^Q] (See note 2) 

Primary Domain: [V2/2,v^) = [0.7071, 1.4142) 

Exceptions 

All arguments outside the domain generate an undefined. NaN. 

Propagated Error 

A = logio(e). R = logio(c)/logJX) 

Generated Error 

Primary Domain Error: WIRE RIWISRE 

Single Length(Standard): 1.70 ulp 0.45 dp 

Single Length(T2 speciai): 1.71 uip 0.46 ulp 

Double Length; 1.84 ulp 0.45 ulp 

The Algorithm 

1 Set iemp:=ALOG(X). 

2 If temp is a Naisl, copy it to the output, otherwise set 
result = log(e) * temp 
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Notes 

1) See note 1 for alog. 

2) The minimum value that can be produced, MinLIQ, is the base-10 
logarithm of the smallest denormalised floating-point number. For sin- 
gle length MmL10 is -44.85, and lor double length It is -323,6. The 
maximum value MaxLIO is the base-10 logarithm o^ XMAX. For single 
length MaxL^O is 38.53, and for double-length it is 308.26. 

3) Since Inf is used to represent a// values greater than XMAX its log- 
arithm cannot be defined. 

4) This function is well-behaved and does not seriously magnify errors in 
the argument. 



EXP 

DEXP 



REAL32 FUNCTION EXP (VAL REA132 X) 
REAL64 FUNCTION DEXP (VAL REAL64 X) 

Compute e^. 
Domain: [-Inf, MaxLog) - [-Inf, 88.72)S, [-Inf, 709.78)D 

Range: [0, Inf) (See note 4) 

Primary Domain: [-Ln2/2,Ln2/2) = [-0.3466. 0.3466) 

Exceptions 

All arguments outside the domain generate an Inf. 

Propagated error 

A = Xe^, R = x 

Generated error 

Primary Domain Error: MRE RMSRE 

Single Length(Standard): 0.99 uip 0.25 ulp 

Single Length(T2 special): 1.0 ulp 0.25 ulp 

Double Length: l.o ulp 0.25 ulp 
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The Algorithm 

1 Set AT ^ integer part of Xf ln(2). 

2 Compute the remainder of X by ln(2), using extended precision 
arithmetic. 

3 Compute the exponential of thie remainder with a floating-point 
rational approximation. 

4 Increase the exponent of the result by JV. If N is sufficiently 
negative the result must be denormalised. 

Notes 

1) MaxLog is \oq^{XMAX), 

2) For sufficiently negative arguments (below -87.34 for single-length 
and below -708.4 for double-length} the output Es denormalised. and so 
the floating-point number contains progressively (ewer significant digits, 
which degrades the accuracy. In such cases the error can theoretically 
be a factor of two. 

3) Although the true exponential function is never zero, for large neg- 
ative arguments the true result becomes too snnall to be represented 
as a floating-point number, and EXP underflows to zero. This occurs for 
arguments below -103.9 for single-length, and below -745.2 for double- 
length. 

4) The propagated error is considerably magnified for large positive ar- 
guments, but diminished for large negative arguments. 



POWER 
DPOWER 



REAL32 FUNCTION POWER (VAL REAIi32 X, Y) 
REAL64 FUNCTION DPOWER (VAL RE1AL64 X, Y) 



Y 



Compute X 

Domain: [0, Inf] x [-Inf, Inf] 

Range: (-Inf, Inf) 

Primary Domain: See note 3, 

Exceptions 

If the first argument is outside its domain, undefined. NaN is returned. If 
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the true value of X^ exceeds XMAX, fnf is returned. In certain other 
cases other NaNs are produced: See note 2. 

Propagated Error 

A - yx^(1 ± log,(X)). R = Y{^± log,(X)) (See note 4) 

Generated error 

Example Range Error: MRE RMSRE (See note 3) 

Single Length(Standard): 1.0 ulp 0.25 ulp 

Single Length(T2 special): 63.1 ulp 13.9 ulp 

Double Length: 21.1 ulp 2,4 utp 

Tlie Algorithm 

Deal with special cases: either argument = 1» 0, +lnf or -fnf (see note 
2). Otherwise: 

(a) For the standard single precision: 

1 Compute L - log,{X) in double precision, where X is the first 
argument. 

2 Compute W = Y X Lin double precision, where Y is the second 
argument. 

3 Compute RESULT = e^ in single precision. 

(b) For double precision, and the single precision special version: 

1 Compute L = loggfx) in extended predsion, where X is the first 
argument, 

2 Compute W = Yxl in extended precisioa where Y Is the second 

argument. 

3 Compute RESULT = 2^ in extended precision. 
Notes 

1) This subroutine implements the mathematical function x"* to a much 
greater accuracy than can be attained using the ALOG and exp functions, 
by performing each step in higher precision. The singie-precision version 
is more efficient than using dalog and EXP because redundant tests are 
omitted. 
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2) Results for special cases are as follows: 



First !nput (X) 


Second input (Y) 


Result 


<0 


ANY 


undefined. NaN 





<o 


undefined. NaN 





< y < XMAX 








Inf 


unstable.NaN 


0<X<1 


Inf 





0<X<1 


-inf 


Inf 


1 


-XMAX <Y < XMAX 


t 


1 


±lnf 


unstabie.NaN 


1 < X < XMAX 


Inf 


Inf 


^ <x< XMAX 


-Inf 





Inf 


1 < y < Inf 


Inf 


Inf 


-inf< y < -1 





Inf 


-1 <y < 1 


undefined.NaN 


otherwise 





1 


otherwise 


1 


X 



3) Performing all the calculations in extended precision makes the double- 
precision algorithm very complex in detail, and having two arguments 
makes a primary domain difficult to specify. As an indication of accuracy, 
the functions were evaluated at 100 000 points logarithmically distributed 
over {0.1, 10.0). with the exponent lineariy distributed over {-35.0, 35.0) 
(single-length), and (-300.0, 300.0) (double-length), producing the er- 
rors given above. The errors are much smaller if the exponent range is 
reduced. 

4) The error amplification factors are calculated on the assumption that 
the relative error in y is ± that in X, otherwise there would be separate 
factors for both X and Y. It can be seen that the propagated error will 
be greatly amplified whenever log^(X) or Y is large. 



SIN 

DSIN 



REAL32 FUNCTION SIM (VAL REAL32 X> 
REAL64 FUNCTION DSIN (VAL REAL64 X) 

Compute sine(X) (where X is in radians). 
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Domain: [-Smax,Smax] = [-205887.4, 205887.4]S (Standard), 

[-4.2 * 10^4.2 * lO^jS (T2 Special) 
= [-3.4*10^3.4*10^]D 

Range: [_i,o,1.0] 

Primary Domain: [-Fi/2,Pi/2] = [-1.57,1.57] 

Exceptions 

All arguments outside the domain generate an inexact.NaN, except ±lnf, 
which generates an undefined. NaN. 

Propagated Error 

A = Xcos{X}. R = Xco\(X) 

Generated error (See note 1) 

Primary Domain [0,2P?] 

i\^RE RiViSRE MAE RMSAE 

Single Length 

(Standard): 0.94 ulp 0.23 ulp 0.96 ulp 0.19 ulp 

Single Length 

(T2 special): 0.92 u!p 0.23 ulp 0.94 ulp 0.19 ulp 

Double Length: 0.9 ulp 0.22 ulp 0.91 ulp 0.18 ulp 

The Algorithm 

1 Set iV = Integer part of \X\/Pu 

2 Compute the remainder of \X\ by Pi, using extended precision 
arithmetic (double precision in the standard version). 

3 Compute the sine of the remainder using a ffoating-point polyno- 
mial. 

4 Adjust the sign of the result according to the sign of the argument 
and the evenness of N. 

Notes 

1) For arguments outside the primary domain the accuracy of the result 
depends crucially on step 2. The extra precision of step 2 is lost if N 
becomes too large, and the cut-off Smax is chosen to prevent this. In 
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any case for large arguments the 'granularity' of floating-point numbers 
becomes a significant factor. For arguments iargertlian Smaz a change 
in the argument of 1 uip would change more than half of the significant 
bits of the result, and so the result is considered to be essentially inde- 
terminate. 

2) The propagated error has a complex behaviour. The propagated rel- 
ative error becomes large near each zero of the function (outside the 
primary range), but the propagated absolute error only becomes large 
for large arguments. In effect, the error is seriously amplified only in an 
interval about each irrational zero, and the width of this interval increases 
roughly in proportion to the size of the argument. 

3) Since only the remainder of X by Pi is used in step 3, the symmetry 
sin(x + n7r) = ±sin(a;) is preserved, although there is a complication due 
10 differing precision representations of tt. 

4) The output range is not exceeded. Thus the output of SiN is always 
a valid argument for asin. 

COS 
DCOS 

REAL32 FUNCTION COS (VAL REAL32 X) 
REAL64 FUNCTION DCOS (VAL REAL64 X) 

Compute cosine(X) (where X is In radians). 

Domain: [-Cmax,Cmax\ = [-205887.4, 205887.4]S (Standard). 

[-1 2868.0, 12868.0]S (T2 special) 
«[~3.4*10^3.4*10^]D 

Range: [-1.0,1.0] 

Primary Domain: See note 1. 

Exceptions 

All arguments outside the domain generate an inexact.NaN, except ±lnf, 
which generates an undefined. NaN. 

Propagated Error 

A = -Xsin(X), R = -Xtan(X) (See note 4) 
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Generated error 
Range: 

Single Length 
(Standard): 
Single Length 
(T2 special): 
Double Length; 

The Algorithm 



[0,Pj/4) [(},2F{\ 

MRE RMSRE MAE RMSAE 

0,93 ulp 0.25 ulp 0.88 ulp 0.18 ulp 

1.1 ulp 0.3 ulp 0.94 ulp 0.19 ulp 

1.0 ulp 0.28 ulp 0.9 ulp 0,19 ulp 



1 Set i\^ = integer part of {\X\+Pi/2)/Pi and compute the remainder 
of {\X\ +Pi/2} by Pi, using extended precision arithmetic (double 
precision in Jhe standard version). 

2 Compute the sine of the remainder using a floating-point polyno- 
mial. 

3 Adjust the sign of the result according to the evenness of N. 
Notes 

1) Inspection of the algorithm shows that argument reduction always oc- 
curs, thus there is no 'primary domain' for COS. So for all arguments the 
accuracy of the result depends crucially on step 2. The standard single- 
precision version performs the argument reduction in double-precision, 
so there is effectively no loss of accuracy at this step. For the T2 special 
version and the double-precisior\ version there are effeclively K extra bits 
in the representation of 7r(K = 8 for the former and 1 2 for the latter). If the 
argument agrees with an odd integer multiple of 7r/2 to more than h bits 
there is a loss of significant bits from the computed remainder equal to 
the number of extra bits of agreement, and this causes a loss of accuracy 
in the result. 

2) The difference between COS evaluated at successive floating-point 
numbers is given approximately by the absolute error amplification factor, 
A. For arguments larger than Cmax this difference may be more than 
half the significant bils of the result, and so the result is considered to 
be essentially indeterminate and an inexact.NaN ts returned. The extra 
precision of step 2 in the double-precision and T2 special versions is lost 
if N becomes too large, and the cut-off at Cmax prevents this also. 

3) For small arguments the errors are not evenly distributed. As the 
argument becomes smaller there is an increasing bias towards negative 



72 TDS 276 02 



March 1991 



1.3 Maths libraries 37 

errors (which is to be expected from the form of the Taylor series). For the 
single-lenglh version and X in [-0.1 ,0.1], 62% of the errors are negative, 
whilst for Z in [-0.01,0.01], 70% of them are. 

4) The propagateci error has a complex behaviour. The propagated rel- 
ative error becomes large near each zero of the function, but the propa- 
gated absolute error only becomes large for large arguments. In etfect, 
the error is seriously amplified only in an internal about each irrational 
zero, and the width of this inten/ai increases roughly in proportion to the 
size of the argument 

5) Since only the remainder of (|X| + Pil2) by Pi is used in step 3, the 
symmetry cos(2;-i-n7r) = ±cos(a;) is preserved. Moreover, since the same 
rational approximation is used as in SIN^ the relation cos(a;) = sin(x + 
7r/2) is a[so preserved. However, in each case there is a complication 
due to the different precision representations of tt, 

6) The output range is not exceeded. Thus the output of COS Is always 
a valid argument for ACOS, 

TAN 
DTAN 

REAL32 FUNCTION TAN (VAL REAL32 X} 
REAL64 FUNCTION DTAN (VAL REAL64 X) 

Compute tan(X} (where X is in radians). 

Domain: [-Tmax, Tmax] - [-1 02943.7, 1 02943.7]S(Standard). 

[-2.1 * 10^2.1 * 10^]S(T2 special), 
= [-1.7*10^1-7*10^]D 

Range: {-Inf, Inf) 

Primary Domain: [-PilA.PijA] = [-0.785,0.785] 

Exceptions 

All arguments outside the domain generate an inexact.NaN, except ±Inf, 
which generate an undeflned.NaN. Odd integer multiples of ;r/2 may 
produce unstable.NaN. 

Propagated Error 

A = X{^ +tan^{Jsr)), R^X[\ +tan2(X))/tan(X) (See note 3) 
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Generated error 

Primary Domain Error: NIRE RMSRE 

Single Length{Standard): 1.44 ulp 0.39 ulp 

Single Length(T2 special): 1.37 ulp 0.39 ulp 

Double Length: 1.27 ulp 0.35 ulp 

The Algorithm 

1 Set iV = integar part of X/(Pi/2), and compute the remalncfer of 
X by Pi/2, using extended precision arithmetic. 

2 Compute two floating-point rational functions of the remainder, 
XNum and XDen. 

3 If JV is odd, set RESULT = -XDen/ XNum, Otherwise set 
RESULT - XNum/ XDen. 

Notes 

1) R is large whenever X is near to an integer multiple of 7r/2, and so tan 
is very sensitive to small errors near its zeros and singularities, Thus for 
arguments outside the primary domain the accuracy of the result depends 
crucially on step 2, so this is performed with very high precision, using 
double precision PiJ2 for the standard single-precision function and two 
double-precision floating-point numbers for the representation of 7r/2 for 
the double-precision function. The T2 special version uses two single- 
precision floating-point numbers. The extra precision is lost if JV becomes 
too large, and the cut-off Tmax is chosen to prevent this. 

2) The difference between tan evaluated at successive floating-point 
numbers is given approximately by the absolute error amplification factor, 
A. For arguments larger than Smax this difference could be more than 
half the significant bits of the result, and so the result is considered to be 
essentially indeterminate and an inexactNaN is returned. 

3) Tan is quite badly behaved with respect to errors in the argument. 
Near its zeros outside the primary domain the relative error is greatly 
magnified, though the absolute error is only proportional to the size of 
the argument. In effect, the error is seriously amplified in an interval 
about each irrational zero, whose width increases roughly in proportion 
to the size of the argument. Near its singularities both absolute and 
relative errors become large, so any large output from this function is 
liable to be seriously contaminated with error, and the larger the argu- 
ment, the smaller the maximum output which can be trusted. If step 3 
of the algorithm requires division by zero, an unstable.NaN is produced 
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instead. 

4) Since only the remainder of X by Pi/2 is used in step 3, the symmetry 
Xan{x + nw) = tan(a:) is preserved, although there is a complication due 
to the differing precision representations of tt. Moreover, by step 3 the 
symmetry tan(a;) = 1/tan(7r/2 ~ i) is also preserved. 

AS IN 
DASTN 

REAIi32 FUNCTION ASIN (VAX. REAL32 X) 
REAL64 FUNCTION DASIN (VAL RE1AL64 X) 

Compute sine~^(X) (in radians). 

Domain: [-1.0,1.0] 

Range: [-Pi/2, Pi/2] 

Primary Domain: [-0.5,0.5] 

Exceptions 

All arguments outside the domain generate an undefined. NaN. 

Propagated Error 

A = x/VY^^x^, R = X/{sin~Mx)Vl -x^) 

Generated Error 

Primary Domain [-1 .0, 1 .0] 

MRE RMSRE MAE RMSAE 

Single Length: 0.58 ulp 0.21 ulp 1.35 ulp 0.33 ulp 

Double Length: 0,59 ulp 0.21 ulp 1 .26 ulp 0.27 ulp 

The Algorithm 

1 If |X| > 0.5, seiXwork := SQRT ((1 - \X\}/2) . Compute Rwork = 
arcsine(-2 + Xtvork) with a floating-point rational approximation, 
and set the result = Rwork + Pi/2. 

2 OtheAvise compute the result directly using the rational approxi- 
mation. 

3 In either case set the sign of the result according to the sign of 
the argumenl. 
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Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there is a small interval at each end of the domain in which 
the result is liable to be contaminated with error: however since both 
domain and range are bounded the absolute error in the result cannot 
be large. 

2) By step 1, the identity sin"^(x) = 7r/2 - 2sin"\^(1 - x)/2)) is pre- 
served. 

ACOS 
DACOS 

REAL32 FUNCTION ACOS (VAL REAL32 X) 
REAL64 FUNCTION DACOS (VAL REAL64 X) 

Compute cosine-"" (X) (In radians). 

Domain: [-1.0,1.0] 

Range: lO,Pi] 

Primary Domain: [-0.5,0.5] 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 
Propagated Error 



A = -X/VT^^X^, R = -X/(sin- ' (X)^/^^Y^) 
Generated Error 

Primary Domain [~1 -0, 1 .0] 

IVIRE RIVISRE MAE RIVISAE 

Single Length: 1.06 ulp 0.38 ulp 2.37 ulp 0.61 ulp 

Double Length: 0.9$ ulp 0.32 ulp 2.25 ulp 0.53 ulp 

The Algorithm 

1 If \X\ > 0.5, set Xwork := SQrt ((1 ^ \X\)/2) . Compute 
Rwork = arcsine(2 * Xwork) with a floating-point rational approx- 
imation. If the argument was positive, this is the result, otherwise 

set the result = Pi - Rwork. 
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2 Otherwise compute Rwork directly using the rational approxima- 
tion. If the argument was positive, set resu\\ = Pi/2- Rwork, 
otherwise result = Pi/2 + Rwork. 

Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there Is a small interval at each end of the domain in which 
the result is liable to be contaminated with error, although this interval is 
larger near 1 than near -1 , since the function goes to zero with an infinite 
derivative there. However since both the domain and range are bounded 
the absolute error in the result cannot be large. 

2) Since the rational approximation is the same as that in ASIN, the 
relation cos~^(z) = 7r/2 -sin"^^) is preserved. 



ATAN 
DATAN 



REAli32 FUNCTION ATAN (VAL REAL32 X) 
REAL64 FUNCTION DATAN (VAL RK7VL64 X) 

Compute tan-"'(X) (in radians). 

Domain: [-Inf, Inf] 

Range: [-^1/2,^172] 

Primary Domain: l-z,z], s^2 - \/3 = 0.2679 

Exceptions 

None. 
Propagated Error 

A^X/(^ ^X\ R = X/(\an'\X)(^ +X^)) 

Generated Error 

Primary Domain Error: MRE RMSRE 

Single Length: 0.56 ulp 0.21 ulp 

Double Length: 0.52 ulp 0.21 u[p 
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The Algorithm 

1 If \X\ > 1.0. set Xwork = 1/|X|, Otherwise Xwork = \x\. 

2 If Xmork > 2 - \/3, sel F = {Xwork ^ y/3 - ^)/{X•work + \/3). 
Otherwise F ^ Xwork. 

3 Compute Rwork = arctan{F) with a floating-point rational approx- 
imation. 

4 If Xwork was reduced in (2), set R = Pi/6 + Rwork, otherwise 

R = Rwork. 

5 If X was reduced in (1), set RESULT = Pi/2 - R, otherwise 
RESULT = R. 

6 Set the sign of the RESULT according to the sign of the argu- 
ment. 

Notes 

1) For \Xl > ATmax, |tan-^(^)| is indistinguishable from jr/2 in the 
floating-point format. For single-length, ATmax = 1.68 * 10^ and for 
double-length ATmax = 9 + 10^^, approximately. 

2) This function is numerically very stable, despite the complicated argu- 
ment reduction. The worst errors occur just above 2 - v^, but are no 
more than 3.2 ulp. 

3) It is also veTy well behaved with respect to errors in the argument, i.e. 
the error amplification factors are always smafl. 

4) The argument reduction scheme ensures that the identities tan~^ (x) = 
7r/2-tan-^^(1/X), and 

tan-''(X) =7r/6 4-tan-''{(v^*X- ^)/{^/3 + X}) are preserved. 



ATAN2 

DATAN2 



REAL32 FUNCTION ATAN2 (VAL REAL32 X, Y) 
REAL64 FUNCTION DATAN2 (VAL REAL64 X, Y) 

Compute the angular co-ordinate tan^^(F/A:) (in radians) of a point 
whose X and Y co-ordinates are given. 
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Domain: [-Inf, Inf] x [-Inf, Inf] 

Range: (-PhPi] 

Primary Domain: See note 2. 

Exceptions 

(0, 0) and (±lnf,±Inf) give undefined. NaN. 

Propagated Error 

A = X(1 ±Y)/(X^^Y% R = X{^±Y)/{Xan-\YfX)(X^ + Y'^)) (See 
note 3) 

Generated Error (See note 2) 

The Algorithm 

1 If X, the first argument, is zero, set ttie result to ±7r/2, according 
to the sign of Y, the second argument. 

2 Otherwise set Rwork:= atan {Y/X) . Then if y < 
set RESULT = RwotIc - Pi, Otherwise set 
RESULT = Pi - Rwork. 

Notes 

1) This two-argument function is designed to perform rectangular-to-polar 
co-ordinate conversion. 

2) See the notes for atan for the primary domain and estimates of the 
generated error. 

3) The error amplification factors were derived on the assumption that 
the relative error in y is ± that in X, olhenwise there would be separate 
factors for X and y. They are small except near the origin, where the 
polar co-ordinate system is singular. 

SINH 
DSINH 

REAL32 FUNCTION SINH (VAL KEAL32 X) 
REAL64 FUNCTION DSINH (VAL REA164 X) 

Compute sinh(X). 
Donnafn: [- Umax, H max] = l-B9A,&SA]S, [-710.5,710.5]D 
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Range: (-inf, Inf) 

Primary Domain: (-1.0,1.0) 

Exceptions 

X < -Hmax gives -Inf, and X > Hmaa; gives Inf. 

Propagated Error 

A = Xcosh(X), R = Jf coth(:5£^) (See note 3) 

Generated Error 

Primary Domain [1 .0, XBig] (See note 2) 

MRE RMSRE MRE RMSRE 

Single Length: 0.91 ulp 0.26 ulp 1.41 ulp 0.34 ulp 

Double Length: 0.67 ulp 0.22 ulp 1.31 ulp 0.33 ulp 

The Algorithm 

1 If \X\ > XBig, set Rwork:= EXP ([X| -ln(2)). 

2 If XBig > \X\ > 1.0, set Jemp:=: EXP i\X\} , and set 
Rvjork = [temp — 1 /temp)/2. 

3 Otherwise compute sinh(|X|) with a floating-point rationaf approx- 
imation. 

4 In all cases, set RESULT = ±Rtuork according to the sign of X. 
Notes 

1) Hmax is the point at which sinh(X) becomes too large to be repre- 
sented in the floating-point format. 

2) XBig is the point at which e"l^l becomes insignificant compared with 
el^J. (in floating-point), For single-length it is 8.32, and for double-length 
it is 18.37. 

3) This function is quite stable with respect to errors In the argument. 
Relative error is magnified near zero, but the absolute error is a better 
measure near the zero of the function and it is diminished there. For 
large arguments absolute errors are magnified, but since the function is 
itself large, relative error is a better criterion, and relative errors are not 
magnified unduly for any argument in the domain, although the output 
does become less reliable near the ends of the range. 
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COSH 
DCOSH 

REAL32 FUNCTION COSH (VAL REAL32 X) 
REAL64 FUNCTION DCOSH (VAL RZAL64 X) 

Compute cosh(X). 
Domain: l-Hmax, Hmax] = [-89.4, 89.4]S. [-71 0.5, 710.5]D 

Range: [l.O, Inf) 

Primary Domain: [-XBig.XBig] = [-8.32,8.32]S 

[-18,37, 1S,37]D 

Exceptions 

|X| > Hmax gives Inf. 

Propagated Error 

A = Xsinh(X). R = Xtanh(X) (See note 3) 

Generated Error 

Primary Domain Error: WIRE RMS 
Single Length: 1.24 ulp 0.32 ulp 

Double Length: 1.24 ulp 0.33 ulp 

The Algorithm 

1 If \X\ > XBig, set Tesult:= EXP {\X\ - ln{2)) . 

2 Otherwise, set Ump:= EXp {\X\) , and set 
result = (temp + 1 /iemp)/2. 

Notes 

1) Hmax is the point at which cosh{Jf) becomes too large to be repre- 
sented in the floating-point format 

2) XBig is the point at which e"l^l becomes insignificant compared with 
el-^l (in floating-point), 

3) Errors in the argument are not seriously magnified by this function, 
although the output does become less reliable near the ends of the range. 
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TANH 
DTANH 



REALS 2 FUNCTION TANH (VAL REAL32 X) 
REAL64 FUNCTION DTANH (VAL REAL64 X) 

Compute tanh(X). 

Domain: [-Inf, InfJ 

Range: [-1.0,1.0] 

Primary Domain: [-Log(3)/2, Log(3)/2] = [-0.549,0.549] 

Exceptions 

None. 
Propagated Error 

A = X/cosh^(X). R = Xfs\nh{X)cQsh{X) 
Generated Error 

Primary Domain Error: MRE RMS 

Single Length: 0,53 ulp 0.2 ulp 

Double Length: 0.53 uip 0.2 ulp 

The Algorithm 

1 If \X\ > ln(3)/2. set temp:= EXP (|X|/2) . Then set 

Rivorh = 1 — 2/(1 -t-iemp). 

2 Otherwise compute Rwork = tanh(|X|) with a floating-point ratio- 
nal approximation. 

3 In both cases, set RESULT = ±Rwork according to the sign of 
X, 

Notes 

1) As a floating-point number, tanh{X) becomes indistinguishable from 
its asymptotic values of ±1 ,0 for \X\ > IITmax, where ETmax is 8.4 for 
single-length, and 19.06 for double-length. Thus the output of TANH is 
equal to ±1.0 for such X. 

2) This function is very stable and well-behaved, and errors in the argu- 
ment are always diminished by it. 
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RAN 
DRAN 

REAL32,INT32 FUNCTION RAN (VAL INT32 X) 
REAL64,INT64 FUNCTION DRAN (VAL INT64 X) 

These produce a pseudo- random sequence of integers, or a correspond- 
ing sequence of fioating-point numbers between zero and one. x is Ihe 
seed integer that initiates the sequence. 

Domain: Integers (see note 1) 
Range: [0.0. 1.0] x Integers 

Exceptions 

None. 

The Algorithm 

1 Produce the next integer in the sequence: Nk^-^ = {aN^ + 1)»todM 

2 Treat iVj^+i as a fixed-point fraction in [0,1), and convert it to float- 
ing point. 

3 Output the floating point result and the new integer. 
Notes 

1) This function has two results, the first a real, and the second an integer 
(both 32 bits for single-length, and 64 bits for double-length). The integer 
is used as the argument for the next call to RAN, i.e. IE 'carries' the 
pseudo-random linear congruential sequence Nk, and it should be kept 
in scope for as long as RAN is used. It should be initialised before the 
first call to RAN but not modified thereafter except by the function itseif. 

2) If the integer parameter is initialised to the same value, the same 
sequence (both floating-point and integer) will be produced. If a different 
sequence is required for each run of a program it should be initialised to 
some 'random' value, such as the output of a timer. 

3) The integer parameter can be copied to another variable or used in 
expressions requiring randonn integers. The topmost bits are the most 
random. A random integer in the range [0,1,] can conveniently be pro- 
duced by taking the remainder by {L + ^)oi the integer parameter shifted 
right by one bit. If the shift is not done an integer in the range l-L,L] 
wiil be produced. 

4) The modulus M is 2^^ for single-length and 2^ for double-length, and 
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the mLiltipliers. a, have been chosen so that all M Integer will be pro- 
duced before the sequence repeats. However several cfifferent integers 
can produce the same floating-point value and so a floating-point output 
may be repeated, although the sequence of such will not be repealed 
until M calls have been made. 

5) The floating-point result is uniformly distributed over the output range, 
and the sequence passes various tests of randomness, such as the 'ruri 
test', the 'maximum of 5 tesf and the 'spectral test'. 

6) The double-lsngth version is slower to execute, but 'more random' than 
the single-length version. If a highly-random sequence of single-length 
numbers is required, this could be produced by converting the output of 
DRAN to single-length. Conversely if only a relatively crude sequence of 
double-length numbers is required, ran could be used for higher speed 
and its output converted to double-length. 

1.3.3 IMS T400, T414 and T425 elementary function library 

The version of the library described by this section has been written for 32-bJt 
processors without hardware for floating-point arithmetic. Functions from it will 
give results very close, but not identical to, those produced by the corresponding 
functions from the single and double length libraries. 

This is the version specifically intended to derive maximun:; performance from 
the IMS T400, T4r4 and T425 processors. The single-precision functions make 
use of the FMUL instruction available on 32-bit processors without floating-point 
hardware. The library is compiled for transputer class tb. 

The tables and notes at the beginning of section 1 .3 apply equally here. However 
all the functions are contained in one Jibrary. To use this library a program header 
must include the line: 

#USE "tbmaths.lib" 



72TDS276 02 March 1991 



1,3 Maths libraries 49 

Function definitions 

ALOG 

REAL32 FUNCTION ALOG (VAL REAL32 X) 
REAL64 FUNCTION DALOG (VAL REAL64 X) 

These compute: (og^fX) 

Domain: (0,XMAX\ 

Range: [MinLog.MaxLog] [See note 2) 

Primary Domain: [\/2/2,\/2) = [0.7071, 1,4142) 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 

Propagated Error 

A-1, i£=1/log,(X) 

Generated Error 

Primary Domain Error: MRE RIVISRE 
Single Length: 1.19 ulp 0.3S ulp 

Double Length: 2.4 ulp 1.0 ulp 

The Algorithm 

1 Split X into its exponent N and fraction F. 

2 Find the natural log of F with a fixed-point rational approximation, 
and convert it into a floating-point number LnF, 

3 Compute ln{2) * N with extended precision and add It to LnF to 

get the result. 

Notes 

1) The term ln{2) * N \s much easier to compute (and more accurate) 
than LnF, and it is larger provided N is not (i.e. for arguments outside 
the primary domain). Thus the accuracy of the result improves as the 
modulus of \oq{X) increases. 

2) The minimum value that can be produced. MinLog, is the logarithm 
of the smallest denormalised floating-point number. For single length 
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Minlog is -103.28, and for double length it is -745.2. The maximum 
value MaxLog is the logarithm of XMAX. For single-length it is 88.72, 
and for double-length it is 709.78. 

3) Since Int Is used to represent all values greater than XMAX its log- 
arithm cannot be defined. 

4) This function is well-behaved and does not seriously magnify errors In 
the argument. 

ALOG10 

REAL32 FUNCTION ALOGIO (VAL REAL32 X) 
REAL64 FUNCTION DALOGIO (VAL REAi64 X) 

These compute: logiQ(X) 

Domain: [Q.XMAX] 

Range: [MinL10,MttxL10] (See note 2) 

Primary Domain: [\/2/2,v/2) - [0.7071, 1.4142) 

Exceptions 

All arguments outside the domain generate an undefined. NaN. 

Propagated Error 

A - logio(e). R = log,o(e)/log,(X) 

Generated Error 

Primary Domain Error: MRE RMSRE 

Single Length: 1.43 uip 0.39 ulp 

Double Length: 2.64 ulp 0.96 utp 

Tlie Algorithm 

1 Set «emp:= ALOG(X). 

2 If temp is a NaN. copy it to the output, othenwise set 
result = log(c) *temp 

Notes 

1) See note 1 forALOG. 
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2) The minimum value that can be produced, MmL10, is the base-10 
logarithm of the smallest denormalised floating-point number. For sin- 
gle length M^nL^O is -44,85, and for double length it is -323.6. The 
maximum value MaxL^ is the base-1 logarithm of XMAX. For single 
length MaxL^O is 38.53. and for double-length it is 308.26. 

3) Since Inf is used to represent all values greater than XMAX its log- 
arithm cannot be defined. 

4) This function is well-behaved and does not seriously magnify errors in 
the argument 



EXP 



REALS 2 FUNCTION EXP (VAL REAL32 X) 
REAL64 FUNCTION DEXP (VAL REAL64 X) 

These compute: e^ 
Domain: [-Inf. MaxLog) = [-Inf, 88.72)3, [-Inf, 709.78)D 

Range: [0, Inf) (See note 4) 

Primary Domain: l-Ln2/2,Ln2/2) = [-0.3466,0.3466) 

Exceptions 

All arguments outside the domain generate an Inf. 

Propagated Error 

A = Xe^, R = X 

Generated Error 

Primary Domain Error: MRE RMSRE 
Single Length: 0.51 ulp 0.21 u!p 

Double Length: 0.5 ulp 0.21 ulp 

The Algorithm 

1 Set JV = integer part of Xj ln{2). 

2 Compute the remainder of X by ln(2), using extended precision 
arithmetic. 
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3 Convert the rennainder to fixed-point, compute its exponential us- 
ing a fixed-point rational function, and convert the result back to 
floating point. 

4 Increase the exponent of the result by JV. ff N is sufficiently 
negative the result nnust be denormalised. 

Notes 

1) MaxLog is log,(XM^X). 

2) The analytical properties of e= make the relative error of the result 
proportional to the absolute error of the argument. Thus the accuracy 
of step 2, which prepares the argument for the rational approximation, is 
crucial to the performance of the subroutine. It is completely accurate 
when JV = 0, I.e. in the primary domain, and becomes less accurate as 
the magnitude of A'' increases. Since A'' can attain larger negative values 
than positive ones, EXP is least accurate for large, negative arguments. 

3) For sufficiently negative arguments (below -87.34 for single-length 
and below -708.4 for double-length) the output is denormalised, and so 
the floating-point number contains progressively fewer significant digits, 
which degrades the accuracy. In such cases the error can theoretically 
be a factor of two. 

4) Although the true exponential function is never zero, for large neg- 
ative arguments the true result becomes too small to be represented 
as a floating-point number, and exp underflows to zero. This occurs for 
arguments below -103.9 for single-length, and below -745.2 for double- 
length. 

5) The propagated error is considerably magnified for large positive ar- 
guments, but diminished for large negative arguments. 



POWER 



REAL32 FUNCTION POWER <VAL REAL32 X, Y) 
REAL32 FUNCTION DPOWER (VAl REAL64 X, Y) 

These compute: X^ 

Domain: [0, Inf) x [-Inf, Inf] 

Range: (-Inf, Inf) 

Primary Domain: See note 3. 
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Exceptions 

If the first argument is outside its domain, undefined.NaN is returned. If 
the true value of X^ exceeds XMAX, Inf is returned. In certain other 
cases other NaNs are produced: See note 2. 

Propagated Error 

A = YX^{1 ± \0Q,(X)), R = Y[^± l09,(X)) (See note 4) 

Generated Error 

Example Range Error: WIRE RMSRE (See note 3) 
Single Length: 1 .0 ulp 0.24 ulp 

Double Length: 13,2 ulp 1.73 ulp 

The Algorithm 

Deal with special cases: either argument = 1» 0, +lnf or -Inf (see note 
2). Otherwise: 

(a) For single precision: 

1 Compute L = log2(X) in fixed point, where X is the first argument. 

2 Compute W = Y X Lin double precision, where Y is the second 
argument. 

3 Compute 2^ in fixed point and convert to floating-point result. 

(b) For double precision: 

1 Compute L = log2(X) in extended precision, where X is the first 
argument. 

2 Compute W = YxL\n extended precision, where Y is the second 
argument. 

3 Compute RESULT = 2^ in extended precision. 
Notes 

1) This subroutine implements the mathematical function x^ to a much 
greater accuracy than can be attained using the ALOG and EXP functions, 
by performing each step in higher precision. 

2) Results for special cases are as follows: 
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SIN 



First Input (X) 


Second Input (Y) 


Result 


<0 


ANY 


uncfefined.NaN 





<o 


undeflned.NaN 





< r < XMAX 








Inf 


unstable.NaN 


0<X< 1 


Inf 





0<X< 1 


-Inf 


Inf 


1 


-XMAX <Y < XMAX 


1 


1 


± Inf 


unstable.NaN 


1 < A" < XMAX 


Inf 


Inf 


^ <X< XMAX 


~^lnf 





inf 


1 < y < Inf 


Inf 


rnf 


-lnf< y < -1 





Inf 


~i <r <1 


undefined.NaN 


otherwise 





1 


otherwise 


1 


X 



3) Performing all the calculations in extended precision makes the double- 
precision algorithm very complex tn detail, and having two arguments 
makes a primary domain difficult to specify. As an indication of accuracy, 
the functions were evaluated at 100000 points logarithmically distributed 
over (0.1, 10.0), with the exponent Jineariy distributed over (-35,0, 35.0) 
(single-length), and (-300.0,300.0) (double-length), producing the errors 
given above. The errors are much smaller it the exponent range is re- 
duced, 

4) The error amplification factors are calculated on the assumption that 
the relative error in y is ± that in X, otherwise there would be separate 
factors for both X and Y. It can be seen that the propagated error will 
be greatly amplified whenever iog,(X) or Y is large. 



REAL32 FUNCTION SIN (VAL REAL32 X) 
REAL64 FUNCTION DSIN (VAL REAL64 X) 

These compute: sine(X) (where X is in radians) 
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Domairt; [-Smax.Smax] = [-12S6S.0,12868.0iS, 

[-2,1 *10^2.1 *10^]D 
Range: [-1.0,1.0] 

Primary Domain; l-Pi/2,Pi/2] - [-1,57,1.57] 

Exceptions 

All arguments outside the domain generate an inexact.NaN, except ±lnf, 
wlitch generates an undefined. NaN. 

Propagated Error 

A = Xcos{X), R^XC0\{X) 

Generated Error {See note 3) 

Range: Primary Domain [Q,2Pt\ 

MRE RMSRE MAE RMSAE 

Single Length: 0.65 ulp 0.22 ulp 0.74 ulp 0.18 ulp 

Double Length: 0.56 ulp 0.21 ulp 0.64 ulp 0.16 ulp 

The Algorithm 

1 SetN = integer part of \X\/Pi. 

2 Compute the remainder of \X\ by Pi, using extended precision 
arithmetic. 

3 Convert the remainder to fixed-pointy compute its sine using a 
fixed-point rational function, and convert the result back to floating 
poinL 

4 Adjust the sign of the result according to the sign of the argument 
and the evenness of N. 

Notes 

1) For arguments outside the primary domain the accuracy of the result 
depends caicially on step 2, The extended precision corresponds to 
K extra bits in the representation of tt (i^ = 8 for single-length and 12 
for double-length). If the argument agrees with an integer multiple of tt 
to more than K bits there is a loss of significant bits in the remainder, 
equal to the number of extra bits of agreement, and this causes a loss 
of accuracy in the result. 

2) The extra precision of step 2 Is lost if N becomes too large, and the 
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cut-off Smax is chosen to prevent this. Jn any case for large arguments 
the 'granularity' of Uoating-poini numbers becomes a significant factor. 
For arguments larger than Smax a change in the argument of 1 ulp 
would change more than half of the significant bits of the result, and so 
the result is considered to be essentially indeterminate. 

3) The propagated error has a complex behaviour. The propagated rel- 
ative error becomes large near each zero of the function (outside the 
prinrtary range), but the propagated absolute error only becomes targe 
for large arguments. In effect, the error is seriously amplified only in an 
interval about each irrational zero, and the width of this interval increases 
roughly in proportfon to the size of the argument. 

4) Since only the remainder of X by Pi is used in step 3, the symmetry 
sin(i + n7r) = ±sin(x) is preserved, although there is a complication due 
to differing precision representations of tt* 

5) The output range is not exceeded. Thus the output of SIN Is always 
a valid argument for as in. 



COS 



REAL32 FUNCTION COS (VAI, REAL32 X) 
REAL64 FUNCTION DCOS (VAL REAL64 X) 

These compute: cosine (X) (where X is in radians) 

Domain: [-Smax.Smax] = 1-12868.0, 12868.0]S. 

[-2.1 *10^2.1 *10^]D 
Range: [-1.0,1.0] 

Primary Domain: See note 1. 

Exceptions 

Ali arguments outside the domain generate an Inexact.NaN, except ±lnf, 
which generates an undefined.NaN, 

Propagated Error 

A = ~Xs\n(X), R = -xxan{X) (See note 4) 
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Generated Error 

Range: [0,Pi74) [0,2Pil 

MRE RMSRE MAE RMSAE 

Single Length: 1.0 u!p 0.28 ulp 0.81 ulp 0.17 ulp 

Double Length: 0.93 ulp 0.26 ulp 0.76 ulp 0.18 ulp 

The Algorithm 

1 Set TV = integer part of (|X| + Pi/2)/ Pi, 

2 Compute the rennainder of {\X\ + Pi/2) by Pi, using extended 
precision arithnnetic. 

3 Compute the remainder to fixed-point, compute its sine using a 
fixed-point rational function, and convert the result back to floating 
point. 

4 Adjust the sign o( the result according to the evenness of N. 
Notes 

1) Inspection of the algorithm shows that argument reduction always oc- 
curs, thus there is no 'primary domain' for COS. So for all arguments the 
accuracy of the result depends crucially on step 2. The extended pre- 
cision corresponds to K extra bits in the representation of tt (if = 8 for 
single-length and 12 for double length). If the argument agrees with an 
odd integer multiple of tt/Z to more than K bits there is a loss of signifi- 
cant bits in the remainder, equal to the number of extra bits of agreement, 
and this causes a loss of accuracy in the result. 

2) The extra precision of step 2 is lost if N becomes too large, and the 
cut-off Smax is chosen to prevent this. In any case for large arguments 
the 'granularity' of floating-point numbers becomes a significant factor. 
For arguments larger than Smax a change in the argument of 1 ulp 
would change more than half of the significant bits of the result, and so 
the result is considered to be essentially indeterminate, 

3) For small arguments the errors are not evenly distributed. As the 
argument becomes smaller there is an increasing bias towards negative 
errors (which is to be expected from the form of the Taylor series). For the 
single-tength version and X in [-0.1 , 0.1], 62% of the errors are negative, 
whilst for X in [-0.01 ,0,01]. 70% of them are. 

4) The propagated error has a complex behaviour. The propagated rel- 
ative error becomes large near each zero of the function, but the propa- 
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gated absolute error only becomes large for large arguments. In effect, 
the error is seriously amplified only in an interval about each irrational 
zero, and the width of this Interval increases roughly in proportion to the 
size of the argument. 

5) Since only the remainder of {\X\ + Pi/2) by Pi is used in step 3, the 
symmetry cos{x + Tnr) = ±003(2;) is presen/ed. Moreover^ since the same 
rational approximation is used as in sin. the relation cos{x) = sin(j:-f7r/^) 
is also preserved. However, in each case there is a complication due to 
the different precision representations of tt. 

6) The output range is not exceeded. Thus the output of COS is always 
a valid argument for ACQS. 

TAN 

REAL32 F0NCTIOW TAN (VAL REAL32 X) 
REAL64 FUNCTION DTAN (VAL REAL64 X) 

These compute: tan(x) (where X is in radians) 

Domain: [-Tmax, Tmax] = [-6434.0, 6434.0JS 

[-1.05 *10^ 1.05*10^10 
Range: (-Inf, Inf) 

Primary Domain: [-.i'i74,Pt74] = [-0.785,0.785] 

Exceptions 

All arguments outside the domain generate an inexact.NaN, except ±lnt, 
which generate an undefined.NaN. Odd integer multiples of 7r/2 may 
produce unstable.NaN, 

Propagated Error 

A = X(1 +tan2(X)), R = X{^ ^Xan^{X})/\an{X} (See note 4) 

Generated Error 

Primary Domain Error: WIRE RMSRE 
Single Length: 3.5 uip 0.23 uip 

Double Length: 0.69 uip 0.23 uip 

The Algorithm 

1 Set iV = integer part of X/(Pi/2). 
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2 Compute the remainder of X by Pi/^. using extended precision 
arithmetic. 

3 Convert tlie remainder to fixed-point, compute its tangent using a 
fixed-point rational function, and convert the result bacl< to floating 
point. 

4 If A^ is odd, take the reciprocal. 

5 Set the sign of the result according to the sign of the argument. 
Notes 

^) R\s large whenever X is near to an integer multiple of 7r/2, and 
so Ian is very sensitive to small errors near its zeros and singularities. 
Thus for arguments outside the primary domain the accuracy of the result 
depends cnjcially on step 2. The extended precision corresponds to K 
extra bits in the representation of 7r/2 (Jf = 8 lor single-length and 12 for 
double-length), [f the argument agrees with an integer multiple of 7r/2 
to more than K bits there is a loss of significant bits in the remainder, 
approximately equal to the number of extra bits of agreement, and this 
causes a loss of accuracy in the result. 

2) The extra precision of Step 2 is lost if N becomes too large, and the 
cut-off Tmax is chosen to prevent this. In any case for [arge arguments 
the 'granularity' of floating-point numbers becomes a significant factor. 
For arguments larger than Tmax a change in the argument of 1 ulp 
would change more than half of the significant bits of the result, and so 
the result is considered to be essentially indeterminate. 

3) Step 3 of the algorithm has been slightly modified in the double- 
precision version from that given in Cody & Waite to avoid fixed-point 
underflow in the polynomial evaluation for small arguments, 

4) Tan Is quite badly behaved with respect to errors in the argument. 
Near its zeros outside the primary domain the relative error is greatly 
magnified, though the absolute error is only proportional to the size of 
the argument. In effect, the error is seriously amplified in an interval 
about each irrational zero, whose width increases roughly in proportion 
to the size of the argument. Near its singularities both absolute and 
relative errors become large, so any large output from this function Is 
liable to be seriously contaminated with error, and the larger the argu- 
ment, the smaller the maximum output which can be trusted. If step 4 
of the algorithm requires division by zero, an unstable. NaN is produced 
instead. 

5) Since only the remainder of X by Pij2 is used in step 3, the symmetry 
tan{i + Tt7r) = tan(z) is preserved, although there is a complication due 
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to the differing precision representations of ?r. Moreover, by step 4 the 
symmetry tan(i) = 1/lan(7r/2 - x) is also preserved. 



ASIN 

REAL32 F0NCTION ASlN (VAL REAL32 X) 
REAL64 FUNCTIOH DASIN (VAL REAL64 X) 

These compute: sine"^(X) (in radians) 

Domain: [-1.0,1.0] 

Range: [-Pi/2,Pi72] 

Primary Domain: [-0.5,0.5] 

Exceptions 

All arguments outside the domain generate an undefined. NaN. 
Propagated Error 

Generated Error 

Primary Domain [-1 .0, 1 .0] 

MRE RMSRE MAE RIWSAE 

Singie Length: 0.53 ulp 0.21 uip 1.35 ulp 0.33 ulp 

Double Length: 2.8 ulp 1.4 ulp 2.34 ulp 0.64 ulp 

The Algorithm 

1 If |X| > 0.5, set Xwork:^ SQRT ({1 - |X|)/2) . 

Compute Rwork = arcsJne(-2 * Xwork) with a fEoating-point ra- 
tional approximation, and set the result = Rwork + Pi/2. 

2 Otherwise compute the result directly using the rational approxi- 
mation. 

3 In either case set the sign of the result according to the sign of 
the argument. 

Notes 

1) The error amplEfication factors are large only near the ends of the 

domain. Thus there is a smali interval at each end of the domain in which 
the result is liable to be contaminated with error: however since both 
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domain and range are bounded the absolute error in the result cannot 
be large. 

2) By step 1. the identity sin"^(a:) - 7r/2 - Zsin'^^^tl - x)/2)) is pre- 
served. 



ACQS 



REAL32 FUNCTION ACQS (VAL REAL32 X) 
REAL64 FUNCTION DACOS (VAL REAL64 X) 

These compute: cosine""" (^) On radians) 

Domain: [-1.0,1.0] 

Range: [0,J^il 

Primary Domain: [-0.5,0.5] 

Exceptions 

All arguments outside the domain generate an undefined. NaN. 

Propagated Error 

A - -X/V1 - X^, R = -Xj(z\r\'-\XW\-X^) 

Generated Error 

Primary Domain [-1.0,1.0] 

MRE RMSRE MAE RMSAE 

Single Length: 1.1 ulp 0.38 ulp 2.4 ulp 0.61 ulp 

Double Length: 1 .3 ulp 0.34 ulp 2.9 ulp 0.70 ulp 

The Algorithm 

1 If \X\ > 0.5, set Xwork := SQRT ({1 - |X|)/2) . Compute 
Rvjork = arcsine (2 * Xwork) with a floating-point rational approx- 
imation. If the argument was positive, this is the result, othenwise 
set the result = Pi - Rwork. 

2 Otherwise compute Rwork directly using the rational approxima- 
tion. If the argument was positive, set result = Pij2 - Rwork, 
otherwise result = Pi/2 -f Rwork. 
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Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there is a small Inten/al at each end of the domain in which 
the result is liable to be contaminated with error, although this interval is 
larger near 1 than near -1 , since the function goes to zero with an infinite 
derivative there. However since both the domain and range are bounded 
the absolute error in the result cannot be large. 

2) Since the rational approximation is the same as that in ASiK, the 
relation cos""'(x) = 7r/2 - sin"^(3:) is preserved. 

ATAN 

REAL32 FUNCTION ATAN (VAL REAL32 X) 
REAL64 FUNCTION DATAN (VAL REAL64 X) 

These compute: tan-^{A') (in radians) 

Domain: [-Inf, Inf] 

Range: [-Pi/2,Pi/2] 

Primary Domain: [-a, z], z = 2-\/3 = 0.2679 

Exceptions 

None. 

Propagated Error 

A = X/(1 + X^), R = X/{\an-\x){1 +X^)) 

Generated Error 

Primary Domain Error: WIRE RMSRE 
Single Length: 0.53 ulp 0.21 ulp 

Double Length: 1.27 ulp 0.52 ulp 

The Algorithm 

1 If |X| > 1.0, set Xwo^k = ^/\X], Otherwise Xwork = \X\. 

2 If Xwork > 2 - V3, Sei F = (Xwork + \/3 - ^}/{Xwork + v^}, 
Otherwise F = Xwork. 

3 Compute Rwork = afctan(F) with a floating-point rational approx- 
imation. 
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4 If Xwork was reduced in (2), set R = Pi/Q + Rwork, otherwise 
R = Rwork. 

5 \i X was reduced in (1), set RESULT - Pi/2 - R, otherwise 
RESULT = R. 

6 Set the sign of the RESULT according to the sign of the argu- 
ment. 

Notes 

1) For \X\ > ATmax> ltan-^(X)| is indistinguishable from n/2 in the 
floating-point format. For single-length, ATmax = 1.68 * 10^, and for 
double-length ATmax = 9 * 10^^, approximately. 

2) This function is numerically very stable, despite the complicated argu- 
ment reduction. The worst errors occur just above 2 - \/3, but are no 
more than 1.8 ulp. 

3) It is also very well behaved with respect to errors in the argument, i.e. 
the error amplification factors are always small. 

4) The argument reduction scheme ensures that the identities tan"^ (X) = 
?r/2-tan-^(1/X), and 

tan-\X) = 7r/6-^tan-^\(v^*X- 1)/(V5 + X)) are preserved. 

ATAN2 

REAL32 FUNCTION ATAN2 (VAL REAL32 X, Y) 
RSAL64 FUNCTION DATAN2 (VAL REAL64 X, Y) 

These compute the angular co-ordinate tan-\y/X) (in radians) of a point 
whose X and Y co-ordinates are given. 

Domain: [-Inf, Inf] x [-Inf, Inf] 

Range: {-Pi. Pi] 

Primary Domain: See note 2. 

Exceptions 

(0, 0) and {±lnt,±lnf) give undeflned.NaN. 

Propagated Error 

^ = X(1 ± Y)/(X^ + Y^), R^X{^± Y)/{\an-\Y/X){X^ + Y^)) (Sea 
note 3) 
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Generated Error 

See note 2. 
The Algorithm 

1 If X, the first argument, is zero, set the result to ±iv/2, according 
to the sign of Y, the second argument. 

2 OthenA/ise set Rwork := atan (Y/X) . Then if y < set 
RESULT * Rwork - Pi, otherwise set RESULT = Pi - Rwork. 

Notes 

1 ) This two-argument function Is designed to perform rectangular-to-polar 
co-ordinate conversion. 

2] See the notes for ATAM for the primary domain and estimates of the 
generated error. 

3) The error amplification factors were derived on the assumption that 
the relative error in y is ± that in X, otherwise there would be separate 
factors for X and Y. They are small except near the origin, where the 
polar co-ordinate system is singular. 



SINH 



REAL32 FUNCTION SINH (VAL REAL32 X} 
REAL64 FUNCTION DSINH (VAL REAL64 X) 

These compute: sinh(X) 
Domain: [-Hmax,Iimax] = [-89.4,89.4JS, [- 710.5,710.5]D 

Range: (-Inf. Inf) 

Primary Domain: (-1.0,1.0) 

Exceptions 

X < -Emax gives -Inf, and X > Hmax gives Inf. 

Propagated Error 

A - Xcosh(X), R = Xcoth(J5C) (See note 3) 
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Generated Error 

Primary Domain l^.0, XBig] (See note 2) 

MRE RMSRE MRE RMSRE 

Single Length: 0.89 ulp 0.3 ulp 0.93 ulp 0.31 u[p 

Double Length: 1.3 ulp 0.51 ulp 1.0 ulp 0.3 ulp 

The Algorithm 

1 If \X\ > XBig, set Rwork :- EXP (\X\ - ln{2)) . 

2 If XBig > \X\ > 1.0. set temp > EXP <|X|) , and set 
Rwork = (temp — 1 /temp)/2. 

3 Othenwise compute Rwork = sinhdxl) with a fixed-point rational 
approximation, 

4 In all cases, set RESULT = ±Rwork according to the sign of X. 
Notes 

1) Hmax is the point at which sinh{X) becomes too large to be repre- 
sented in the fJoating-point format. 

2) XBig is the point at which £"1^1 becomes insignificant compared with 
el-^l, (in floating-point). For singie-lenglh it is 8.32, and lor double-length 
it isia37. 

3) This function is quite stable with respect to errors in the argument. 
Relative error is magnified near zero, but the absolute error Is a better 
measure near the zero of the function and it is diminished there. For 
large arguments absolute errors are magnified, but since the function is 
itself large, relative error is a better criterion^ and relative errors are not 
magnified unduly for any argument in the domain, although the output 
does become less reliable near the ends of the range. 



COSH 



REAL32 FUNCTION COSH {VAL REAL32 X) 
REAL64 FUNCTION DCOSH (VAL REAL64 X) 

These compute: cosh(x) 
Domain: [-Umax, Hmax] = [-89.4, 89.4]S, [-71 0.5, 71 0.5JD 
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Range: [1.0, Inf) 

Primary Domain: [-XBig,XB%g] = [~8.32,8.32]S 

[-18.37, ie.37]D 

Exceptions 

\X\ > Hmax gives inf. 

Propagated Error 

A = Xsinh(X). R = Xtanh(X) (See note 3) 

Generated Error 

Primary Domain Error: MRE RMS 
Single Length: 0.99 ulp 0.3 ulp 

Doubie Length: 1-23 ulp 0.3 ulp 

The Algorithm 

1 if \X\ > XBig, set result := EXP (|X| - ln{2)) . 

2 Otherwise, set temp := exp (|X|) , and set 

result = {temp + 1 /femp)/2. 

Notes 

1) Hmax is the pofnt at which cosh(x) becomes too large to be repre- 
sented in the floating-point format. 

2) XBig is the point at which e"5^l becomes insignificant compared with 
cl^l (in floating-point). 

3) Errors in the argument are not seriously magnified by this function, 
although the output does become less reliable near the ends of the range. 



TANH 



REAL32 FUNCTION TANH <VAL REAL32 X) 
REAL64 FUNCTION DTANH (VAL REAL64 X) 

These compute: tanh(X) 
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Domain: [-Inf, Inf] 

Range: [-t. 0,1.0] 

Primary Domain: [-Log(3)/2,Log{3)/2]= [-0.549,0.549] 

Exceptions 

None. 

Propagated Error 

A = X/ cosh^iX), i2 = X/sinh(X)cosh(X) 

Generated Error 

Primary Domain Error: MRE RMS 
Single Length: 0.52 ulp 0.2 ulp 

Double Length: 4.6 ulp 2.6 ulp 

The Algorithm 

1 If \X\ > ln(3)/2, set temp := EXP (|X|/2) . Tlien set 
Rwork = 1 - 2/(1 + temp), 

2 Othenwise compute Rwork =tanh([X|) with a tloating-point ratio- 
nal approximation, 

3 In both cases, set RESULT = ±Rwork according to the sign of 
X. 

Notes 

1) As a lloating-point number, tanh(X) becomes indistinguishable from 
Its asymptotic values of i1 .0 for |X| > HTmax, where HTmax is 8.4 for 
single-length, and 19,06 for double-length. Thus the output of TT^H is 
equal to ±1 .0 for such X. 

2) This function is very stable and well-behaved, and errors in the argu- 
ment are always diminished by it. 

RAN 

RZAL32,INT32 FUNCTION RAN (VAL INT32 X} 
REAL64,INT64 FUNCTION DRAN (VAL INT64 X) 

These produce a pseudo-random sequence of integers, and a corre- 
sponding sequence oHIoating-point numbers between zero and one. 
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Domain: Integers (see note 1) 
Range: [0.0. 1.0] x Integers 

Exceptions 

None. 

The Algorithm 

1 Produce the next integer in the sequence: Nk+^ = {aNt + ^)r^dM 

2 Treat N^+i as a fixed^point fraction in [0,1), and convert it to lloat- 
ing point. 

3 Output the floating point result and the new integer. 
Notes 

1) This function has two results, the first a reai, and the second an integer 
(both 32 bits for single-iength. and 64 bits fordouble-iength). The integer 
is used as the argument for the next call to ran, i.e. it 'carries' the 
pseudo-random linear congruentlal sequence N^, and it should be kept 
in scope for as long as ran is used. It should be initialised before the 
first call to ran but not modified thereafter except by the function itself. 

2) If the integer parameter is initialised to the same value, the same 
sequence (both floating-point and integer) will be produced. If a different 
sequence is required for each run of a program il should be initialised to 
some 'random' value, such as the output of a timer. 

3) The integer parameter can be copied to another variable or used in 
expressions requiring random integers. The topmost bits are the most 
random. A random integer in the range [0,L] can conveniently be pro- 
duced by taking the remainder by (1- + 1 ) of the integer parameter shifted 
right by one bit. If the shift is not done an integer in the range l-L,L] 
wiil be produced. 

4) The modulus M is 2^^ for single-length and 2" lor double-length, and 
the multipliers, a, have been chosen so that all M integers will be pro- 
duced before the sequence repeats. However several different integers 
can produce the same floating-point vaJue and so a floating-point output 
may be repeated, although the sequence of such will not be repeated 
until M calls have been made. 

5) The floating-point result is uniformly distributed over the output range, 
and the sequence passes various tests of randomness, such as the 'run 
test', the 'maximum of 5 test' and the 'spectral test'. 
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6) The double-length version is slower to execute, but 'more random' than 
the single-length version. If a highly-random sequence of single-length 
numbers is required, this could be produced by converting the output of 
DRAN to single-length. Conversely if only a relatively crude sequence of 
double-length numbers is required, ran could be used for higher speed 
and its output converted to double-length. 
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1.4 Host file server library 

Library: hostio.iib 

The host file server library contains routines that are used to communicate with 
the host file server. The routines are independent of the host on which the server 
IS running. Using routines from this library you can guarantee that programs will 
be portable across all implementations of the toolset. 

Constant and protocol definitions for the hostio library, including error and return 
codes, are provided in the include file hostio . inc. A listing of the fi!e can be 
found in appendix C. 

The result value from many of the routines m this library can take the value > 
spr. operation. failed which is a server dependent failure result. It has 
been left open with the use of > because future server implementations may 
give more information back via this byte. 

1.4.1 Errors and the C run time library 

The hostio routines use functions provided by the host file server. These are 
defined in appendix H. The server is implemented in C and uses routines in a 
C njn time library, some of which are implementation dependent. 

In particufar, the hostio routines do not check the validity of stream identifiers, and 
the consequences of specifying an incorrect streamid may differ from system 
to system. For example, some systems may return an error tag, some may 
return a text message. If you use only those stream ids returned by the hostio 
routines that open files (so -open, so . open . temp, and scpopen.read), 
invalid ids are unlikely to occur. 

It is also possible in rare circumstances for a program to fail altogether with an 
invalid streamid because of the way the C library is impJemented on the system. 
This error can only occur if direct use of the library to perform the operation 
would produce the same error. 

1.4.2 Inputtmg real nun^bers 

Routines for inputting real numbers only accept numbers in the standard OCCam 
format for REAL numbers. Programs that allow other ways of specifying real 
numbers must convert to the OCCam format before presenting them to the library 
procedure. 

For details of OCCarn syntax for real numbers see the 'Occam 2 Reference 
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Manuar. 

1A3 Procedure descriptions 

In the procedure descriptions, f s is the channel from the host fiie sen/er, and 
ts is the channei to the host file server. The SP protocoi used by the host file 
server channels is defined in the inciude file hostio.inc, which is listed in 
appendix C. 

The hoslio routines are divided into six groups: five groups that reflect function 
and use» and a sixth miscellaneous group. The five specific groups are: 

• File access and management 

• General host access 

• Keyboard input 

• Screen output 

• File output. 

Each group of routines Is described in a separate section. Each section begins 
with a list of the routines in the group with their formal parameters. This is 
followed by a description of each routine in turn. 

Note: for those routines Vi/hich write data to a stream (inciuding the screen), if 
the data Is not sent as an entire block then it cannot be guaranteed that the data 
arrives contiguously at its destination. This is because another process writing 
to the same destination may interleave its server request{s) with those of these 
routines. 

1,4.4 File access routines 

This group includes routines for managing file streams, for opening and closing 
files, and for reading and writing blocks of data. 
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Procedure 



so , open 



so . open . t:emp 



so.popen.read 



so . close 
so. read 
so . write 
so. gets 

so. puts 
so. flush 



Parameter Specifiers 



CHAN OF SP fs, ts, VAL []BYTE name, 
VAL BYTE type, mode, INT32 streaioid, 
BYTE result 

CHAN OF SP fs, tS, VAi BYTE type, 

[so , temp . filename . length] BYTE 

filename, 

INT32 streamid, BYTE result 

CHAN OF SP fs, ts, 
VAL []BYTE filename, 
VAL []BYTE path. variable. name, 
VAL BYTE open. type, INT full.len, 
[]BYTE full. name, INT32 streamid, 
BYTE result 

CHAN OF SP fs, ts, VAL INT32 streamid, 
BYTE result 

CHAN OF SP fs, ts, VAL 1NT32 Streamid, 
INT length, [JBYTE data 

CHAN OF SP fs, ts, VAL INT32 streamid, 
VAL []BYTE data, INT length 

CHAN OF SP fs, ts, VAL INT32 streamid, 
INT length, []BYTE data, BYTE result 

CHAN OF SP fs, ts, VAL INT32 Streamid, 
VAL []BYTE data, BYTE result 

CHAN OF SP tsr ts, VAL INT32 streamid, 
BYTE result 
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Procedure 


Parameter Specifiers 


so . seek 


CHAN OF SP fs, ts, 
VAL INT32 streamid, 






VAL INT32 offset, origin, BYTE resu 


It 


so. tell 


CHAM OF SP fs, ts, 

VAL INT32 streamid, 

INT32 position, BYTE result 




so>eof 


CHAN OF SP fs, ts, 

VAL INT32 streamid, BYTE result 




so -f error 


CHAN OF SP fs, ts, 

VAL INT32 streamid, INT32 error.no, 

IHT length, []BYTE message, 

BYTE result 




so * remove 


CHAN OF SP fs, ts, VAL []BYTE name, 

BYTE result 




so . rename 


CHAN OF SP fs, ts, 

VAL []BYTE oldname, newname, 

BYTE result 




so. test .exists 


CHAN OF SP fs, ts, 

VAL [jBYTE filename, BOOL exists 





Procedure definitions 



so .open 



PROG so. open 



(CHAN OF SP fs, ts, 
VAL []BYTE name, 
VAL BYTE type, mode, 
INT32 Streamid, BYTE result) 



Opens the file given by name and returns a stream identifier streamid 
for alf future operations on the file until it is closed. If name does not 
include a directory then the file is searched for in the current directory- 
File type is specified by type and the mode o( opening by mode. 

type can take the following values: 

apt .binary File contains raw bytes only. 

spt.text File contains text records separated by 
newline sequences. 
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mode can take the following values: 



spm , input: 
spm . output 

spm, append 



Open existing file for reading. 

Open new file, or truncate an existing 
one, for writing. 

Open a new fKe, or append to an exist- 
ing one, for writing. 

spm, existing, update Open an existing file for update (reading 

and writing), starting at beginning of the 
file. 

spm. new. update Open new file, or truncate existing one, 

for update. 

spm , append . update Open new file, or append to an existing 

one, for update. 

result can take the following values: 



spr.ok 

spr, bad, name 

spr* bad. type 

spr. bad. mode 

spr. bad. packet . size 

> spr, operation. failed 



The open was successful. 
Null file name supplied. 
Invalid file type. 
Invalid open mode. 
File name too large (i.e. 

> sp, max .openname . size) 
If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections 0.1 and H.2.2). 



so . open . temp 



PROC so. open. temp 

(CHAN OF SP fs, tSr 
VAL BYTE type, 

[so .temp , filename . length] BYTE filename, 
INT32 streamidr BYTE result) 

Opens a temporary file in spm* new. update mode. The first filename 
tried is tempo 0, If the file already exists the nn suffix on the name 
temp/1/7 is incremented up to a maximum of 9999 until an unused num- 
ber is tound. If the number exceeds 2 digits the last character of temp 
is ovenwritten. For example: if the number exceeds 99 the p is over- 
written , as in tem999; if the number exceeds 999, the m is overwrit- 
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ten, as in te9999. File type can be spt. binary or spt-text, 
as with so. open. The name of the file actualty opened is returned in 
filename. 

The result returned can take any ot the following values: 

spr . ok The open was successful. 

spr.notok There are already 10,000 temporary 

files. 
spr , bad. type Invalid file type specified. 

> spr , operation . failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2.2}. 

so . popen . read 

PROC so. popen. read 

(CHAN OF SP fs, ts, 
VAL []BYTE filename, 
VAL []BYTE path. variable. name, 
VAL BYTE open. type, 
INT full.len, []BYTE full. name; 
INT32 streamid, BYTE result) 

As for so, open, but if the file is not found and the fifename does not 
include a directory, the routine uses the directory path string associated 
with the host environment variable, given in path. variable. name, 
and performs a search in each directory in the path in turn. This corre- 
sponds to the searching rufes used by the toolset, using the environment 
variable ISEARCH. see part 1, section 2.10.3. 

File type can be spt. binary or spt. text, as with so. open. The 
mode of opening is always spm . input. 

The name of the file opened Is returned in full, name, and the length of 
the file name is returned in full . len. It no file is opened, full . len 
and full. name are undefined, and the result will not be spr. ok. 

The result returned can take any of the following values: 
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spr . ok The open was successful. 

spr . bad . name NulJ name supplied. 

spr. bad. type Invalid fife type specified. 

spr. bad. packet .size File name too large 

(i.e. > sp. max. openname. size) 
or path. variable. name 
is too large (i.e. 

> sp. max. getenvname. size). 

spr. buffer .overflow The environment string referenced by 

path. variable. name is longer 
than 256 characters. 

> spr, operation. failed If result lakes a value 

> spr. operation, failed 

then this denotes a server returned 
failure. (See sections C.1 and H. 2.2). 

so. close 

PROC so, close (CHAN OF SP fs^ ts, 
VAL IKT32 streamid, 
BYTE result) 

Closes the stream identified by streamid. 

The result returned can take any of the foHowing values: 

spr , ok The dose was successful. 

> spr . operation . failed if result takes a value 

> spr. operation. failed 

then this der>otes a server returned 
failure. (See sections C.1 and H.2.2). 
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so. read 



PROC so. read (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT length, []BYTE data) 

Reads a block of bytes from the specified stream up to a maximum given 
by the size of the array data. If length returned is not the same as 
the size of data then the end of the file has been reached or an error 
has occurred. 



so , write 



PROC so. write (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
VAL []ByTE data, 
INT length) 

Writes a block of data to the specified stream. If length is less than 
the size of data then an error has occurred. 



so . gets 



PROC so. gets (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT length, [IBYTE data, 
BYTE result) 

Reads a line from the specified input stream. Characters are read until 
a newline sequence is found, the end of the file is reached, or 
sp. max. reac^uffer, size characters have been read. The charac- 
ters read are in the first length bytes of data. The newline sequence 
is not included in the returned array. If the read fails then either the end 
of file has been reached or an error has occurred. 

The result returned can take any of the following values: 
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spr . ok 

spr. bad. packet . size 

spr , buffer . overflow 
> spr , operation . failed 



The read was successful. 

data is too large 

{> sp. max. readbuffer .size). 

The line was larger than the buffer 
data and has been truncated to fit. 

If result takes a value 

> spr. operation, failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2,2). 



so. puts 



PROC so. puts (CHAH OF SP fs, ts, 
VAL INT32 streamid, 
VAL []BYTE data, BYTE result) 

Writes a fine to the specified output stream. A newline sequence is added 
to the end of the line. The size of data must be less than or equal to 
the hostio constant sp. max. writebuffer, size. 

The result returned can take any of the following values: 



spr .ok 

spr * bad. packet .size 

> spr . operation . failed 



The write was successful. 

SIZE data is too large ( > 

sp .max . writebuffer . size). 

If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 



so, flush 



PROC SO, flush (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
BYTE result) 

Flushes the specified output stream. All internally buffered data is written 
to the stream. Write and put operations that are directed to standard 
output are flushed automatically. The stream remains open. 

The result returned can take any of the following values: 
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spr . ok The flush was successful . 

> spr . operation . failed If result takes a value 

> spr . operation . failed 

then this denotes a server returned 
failure. (See sections C.1 and H. 2.2). 



so. seek 



PROC so. seek (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
VAL IKT32 offset, origin, 
BYTE result) 

Sets the file position for the specified stream. A subsequent read or write 
will access data at the new position. 

For a binary file the new position will be offset bytes from the position 
defined by origin. For a text file offset must be zero or a value 
returned by so, tell, in which case origin must be spo. start. 

origin may take the following values: 

spo . start The start of the file. 

spo . current The Current position in the file. 

spo . end The end of the file. 

The result returned can take any of the following values: 

spr. ok The operation was successful. 

spr. bad. origin Invalid origin. 

> spr , operation . failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2.2). 



so. tell 



PROC so. tell (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT32 position, BYTE result) 

Returns the current file position for the specified stream. 
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The result returned can take any of the following values: 

spr.ok The operation was successful. 

> spr. operation, failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. {See sections C.I and H.2.2]. 



so.eof 



PROC so.eof (CHAN OF SP fs, ts, 

VAIi INT32 streamid, BYTE result) 

Tests whether the specified stream has reached the end of a file. The 
end of file is reached when a read operation attempts to read past the 
end of fife. 

The result returned can take any of the following values: 

spr. ok End of file has been reached. 

> spr , operation . failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2.2). 
This result will also be obtained if eof 
has not been reached. 



so . f error 



PROC so. f error (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT32 error.no, INT length, 
r]BYTE message, BYTE result) 

Indicates whether an error has occurred on the specified stream. The 
integer error.no is a host defined error number. The returned mes- 
sage is in the first length bytes of message, length will be zero 
if no message can be provided. Jf the returned message is longer than 
505 bytes then it is truncated to this size. 

The result returned can take any of the following values: 
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spr . ok 

spr .buf f er . overflow 

> spr .operation. failed 



An error has occurred on the speci- 
fied stream. 

An error has occurred but the mes- 
sage is too large for message and 
has been truncaled to fit. 

If result takes a value 

> spr .operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 
This resutt wjji also be obtained if no 
error has occured on the specified 
stream. 



so . remove 



PROC so. remove {CHAN OF SP fs, ts, 

VAL []BYTE name, BYTE result) 

Deletes the specified fi(e. 

The result returned can take any of the following values: 



spr . ok 

spr .bad. name 

spr . bad . packet .size 



The delete was successful. 

Nuli name supplied. 

SIZE name is too large ( > 
sp .max . removename . size). 

> spr . operation . failed If result takes a value 

> spr ♦Operation. failed 

then this denotes a server returned 
failure. (See sections C.l and H.2.2). 



so . rename 



PROC so. rename (CHAN OF SP fs, ts, 

VAL []BYTE oldname, newname^ 
BYTE result) 

Renames the specified file. 

The result returned can take any of the following values: 
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spr .ok 

spr .bad. name 

spr . bad . packet . size 



The operation was successfui. 

Null name supplied 

File names are too large 
(SIZE namel + SIZE name2 > 
sp.max.renamename. size). 

> spr, operation, failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 



so .test .exists 

PROC so, test, exists (CHAN OF SP fs, ts, 

VAL []BYTE filename, 
BOOL exists) 

Tests if the specified file exists. The value of exists is true if the file 
exists, otherwise it is false. 



1.4.5 General host access 

This group contains routines to access the host computer for system information 
and services. 



Procedure 


Parameter Specifiers 


so . coinmandline 


CHAN OF SP fs, ts, 




VAL BYTE all, INT length, 




[]BYTE string, BYTE result 


so , parse. command. line 


CHAN OF SP fs, ts. 




VAL [] []BYTE option. strings, 




VAL [ ] INT 




Option .parameters .required. 




[]BOOL option. exists, 




[][2]INT option. parameters. 




INT error. len, []BYTE line 


so . getenv 


CHAN OF SP fs, ts. 




VAL []BYTE name, INT length. 




[]BYTE value, BYTE result 


so. time 


CHAN OF SP fs, ts. 




INT32 localtime, DTCtime 
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Procedure 



Parameter Specifiers 



so. system 



so . exit 



so , core 



so. version 



CHAN OF SP fs, ts, 

VAL []BYTE command, 

IKT32 status, BYTE result 

CHAN OF SP fs, ts, 
VAL INT32 status 

CHT^ OF SP £s, ts, 

VAL INT32 offset, 

INT bytes -readf 

[]BYTE data, BYTE result 

CHAN OF SP fS; ts, 

BYTE version, host, os, board 



Procedure definitions 



so . coinmandline 



PROC so.commandline (CHAN OF SP fs, ts, 

VAL BYTE all, INT length, 
[]BYTE string, BYTE result) 

Returns the command line passed to the server when it was invoked. 
If all has the value sp, short .cormnandline then all valid server 
options and their arguments are stripped from the command line, as is 
the sen/er command name, if all is sp . whole , coinmandline then 
the command line is returned exactly as it was invoked. The returned 
command line is in the first length bytes of string. If the command 
line string is longer than 509 bytes then it is truncated to this size. 

The result returned can take any of the following values: 



spr . ok 

spr -buffer. overflow 



The operation was successful. 
Command line too long for string 
and has been truncated to fit. 

> spr . operation . failed If result takes a value 

> spr . operation . failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 
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so .parse . command, line 

PROC so, parse. command. line 

(CHAN OF SP fs, ts, 
VAI. [][]BYTE option. Strings, 
VAL []INT option, parameters .required, 
[]BOOL option. exists r 
[][2]INT opt ion. parameters^ 
INT error. len, I]BYTE line) 

This procedure reads the server command line and parses it for specified 
options and associated parameters. 

The parameter option, strings contains a list of all the possible 
options and must be in upper case. Options may be any length up to 
256 bytes and when entered on the command line may be either upper 
or lower case. 

To read a parameter that has no preceding option (such as a file name) 
then the first option string should be empty (contain only spaces). For 
example, consider a program to be supplied with a file name, and any of 
three options 'A', 'B' and 'C. The array option, strings would look 
like this: 

VAL option. strings IS [" ", "A", "B", "C"] : 



The parameter opt ion. parameters . required indicates if the cor- 
responding option (in option. strings) requires a parameter. The 
values it may take are: 

spopt . never Never takes a parameter, 
spopt . maybe Optionally takes a parameter. 
spopt . always Must take a parameter. 

Continuing the above example, if the file name must be supplied and 
none of the options take parameters, except for 'C, which may or may 
not have a parameter, then option .parameters . required would 
look like this: 

VAL option. parameters .required IS 
[spopt .always, spopt .never, 
spopt. never, spopt. maybe] : 

If an option was present on the command fine the corresponding element 
of option . exists is set to TRDE, otherwise it is set to FALSE. 
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If an option was followed by a parameter then the position in the array 
line where the parameter starts and the length of the parameter are 
given by the first and second elements respectively in the corresponding 
element in option. parameters. 

If an error occurs whilst the command line is being parsed then 
error, len will be greater than zero and line will contain an error 
message of the given length. If no error occurs then line will contain 
the command line as supplied by the host file server. 

Most of the possible error messages are setf-explanatcry, however, it is 
worth noting the meaning oi the error 'Command line error: called in- 
correctly'. This error means that either option . strings was null or 
tInatSIZE option. exists, SIZE option,paranieter5 0rSI2:E 
option .parameters . required does not equal 
SIZE Option. Strings. 

so . get en V 

PROC so.getenv (CHAN OF SP fs, ts^ 
VAL I] BYTE name, 
INT length, []BYTE value, 
BYTE result) 

Returns the string defined for the host environment variable name. 
The returned string is in tlie first length bytes of value. If 
name is not defined on the system result takes the value > 
spr. operation. failed. If the environment variable's string is 
longer than 509 bytes then It is truncated to this size. 

The result returned can take any of the following values: 

spr. ok The operation was successful. 

spr. bad* name The specified name is a null string. 

spr * bad. packet .size SIZE name is too large ( > 

sp*max» getenvname . size). 

spr . buffer . overflow Environment string too large for 

value but has been truncated to fit. 

> spr . operation . failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2.2). 



72 TDS 276 02 March 1991 



86 The Occam libraries 



so.txme 



PROC so. time (CHJUfl OF SP fs, ts, 

1NT32 localtime, DTCtiine) 

Returns the local time and Coordinated Universal Time. Both times are 
expressed as the number of seconds that have elapsed since midnight 
on 1st January, 1970. If UTCtime is unavailable then it will have a value 
of zero. The times are given as unsigned int32s. 



so. system 



PROC so. system (CHAN OF SP fs, ts, 
VAL []BYTE command, 
INT32 status, BYTE result) 

Passes the string command to the host command processor for execu- 
tion. If the command string is of zero length result takes the value 
spr.ok li there is a host command processor, othenwise an error is 
returned. ]f command is non-zero in length then status contains the 
host-specified value of the command, othenwise it is undefined. 

The result returned can take any of the following values: 

spr . ok Host command processor exists. 

spr. bad. packet .size The array command is too large ( > 

sp . max . systemcommand. size). 

> spr . operation . failed if result takes a value 

> spr .operation .failed 

then this denotes a server returned fail- 
ure. (See sections C.1 and H.2.2). 



so. exit 



PROC so. exit (CHAN OF SP fs, ts, 
VAi INT32 Status) 

Terminates the sender, which returns the value of status to its caller 
\i status has the special value sps. success then the server will 
terminate with a host specific 'success' result. If status has the special 
value sps . failure then the server will terminate with a host specific 
'failure' result. 
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so ,core 



PROC so .core (CHAN OF SP fs, ts, 

VAIi INT32 offset, INT bytes . read, 
[JBYTE data, BYTE result) 

Returns the contents of the root transputer's memory as peeked from the 
transputer when iserver is invoked with the analyse (*SA') option. The 
start of the memory segment is given by offset which is an offset from 
the base of memory (and is therefore positive). The number of bytes to 
be read is given by the size of the data vector The nun:iber of bytes 
actually read into data is given by bytes . read. An error is returned 
if offset is larger than the total amount of peeked memory. 

The result returned can take any of the following values: 

spr.ok The operation was successfuf. 

spr. bad. packet. size The array data is too targe (> 

sp .max . corerequest . size). 

> spr. operation, failed If result takes a value 

> spr . operation . failed 

then this denotes a server returned fail- 
ure. (See sections C,1 and H.2.2). 

This procedure can also be used to determine whether the memory was 
peeked (whether the server was invoked with the 'SA' option), by spec- 
ifying a size of zero for data and offset. It the result returned is 
spr . ok the memory was peeked. 



so. version 



PROC so. version (CHAN OF SP fs, ts, 

BYTE version, host, os, board) 

Returns version information about the sen/er and the host on which it is 
running. A value of zero for any of the items indicates that the information 
is unavailable. 

The version of the server is given by version. The value should be 
divided by ten to yield the true version number. For example, a value of 
15 means version 1.5. 

The host machine type is given by host, and can take any of the follow- 
ing vdues: 
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IBM PC 

IBM 370 Architecture 

NEC PC 

DEC VAX 

Sun Microsystems Sun 3 

Sun Microsystems Sun 4 
3ph.B0X.SDN386 Sun Microsystems Sun 386i 
sph . BOX . APOLLO ApoHo 



sph . PC 
sph.S370 
sph.NECPC 
sph. VAX 
sph . SUN3 
Sph.B0X-SaN4 



Values up to 127 are reserved Jor use by INMOS. 

The host operating system is given by os, and can take any of the fol- 
lowing values: 

spo.DOS DOS 

spo. HELIOS HEUOS 

spo.VMS VMS 

spo. SUNOS SunOS 

spo, CMS CMS 



Values up to 127 are reserved for use by INMOS. 

The interface board type is given by board, and can take any of the 
following values: 



spb.B004 

spb.BOOS 

spb.BOlO 

spb.BOll 

spb.B014 

spb.BOlS 

spb.BOie 

spb.DRXll 

spb . IBMCAT 

Spb.QTO 

Spb.UDPLINK 



IMS 8004 
IMS 8008 
IMSB010 
IMS B011 
IMS B014 
IMS B015 
IMSB016 
DRX-1 1 
CAT 

Capiin QTO 
UDPIJnk 
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Values up to 127 are reserved lor use by INWOS. 



1.4,6 Keyboard input 



Procedure 


Parameter Specifiers 


so.pollkey 


CHAN OF SP fs, tS; 




BYTE key, result 


so.getkey 


CHAN OF SP fs, ts, 




BYTE key, result 


so. read. line 


CHAN OF SP fs, ts, 




IKT len, []BYTE line, 




BYTE result 


so . read . echo . line 


CHAN OF SP fs, ts. 




INT len, []BYTE line, 




BYTE result 


so. ask 


CHAN OF SP fs, ts. 




VAL []BYTE prompt, replies, 




VAL BOOL 




display. possible. replies. 




VAL BOOL echo. reply. 




INT reply, number 


so . read . echo . int 


CHAN OF SP fs, ts, INT n, 




BOOL error 


so , read . echo , int32 


CHAN OF SP fs, ts, 




1KT32 n, BOOL error 


so » read, echo . int64 


THAN OF SP fs, ts. 




INT64 n, BOOL error 


so . read , echo , hex . int 


CHAN OF SP fs, ts. 




INT n, BOOL error 


so . read - echo . hex . int32 


CHAN OF SP fs, ts. 




INT32 n, BOOL error 


so. read. echo. hex, int €4 


CHAN OF SP fs, ts, 




INT64 n, BOOL error 


s o . read . echo . any , int 


CHAN OF SP fs, ts, 




INT n, BOOL error 


so , read . echo . real32 


CHAN OF SP fs, ts, 




REAL32 n, BOOL error 


so . read . echo . real 64 


CHAN OF SP fs, ts. 




REAL64 n, BOOL error 
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Procedure definitions 

so .pollkey 

PROC SO. pollkey (CHAN OF SP fs, ts, 
BYTE key J result) 

RGads a single character from the keyboard. If no key is available then it 
returns immediately with > spr. operation, failed. The key is not 
echoed on the screen. 

The result returned can take any of the following values: 

spr . ok A key was available and has been re- 

turned In key, 

> spr. operation. failed if result takes a value 

> spr .operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 

so.getkey 

PROC so.getkey (CHAN OF SP fs, ts, 
BYTE key, result) 

As so , pollkey but waits for a key if none is available. 

so. read. line 

PROC so. read. line (CHAN OF SP fs, ts, INT len, 
[]BYTE line, BYTE result) 

Reads a line of text from the keyboard, without echoing It on the screen. 
The characters read are in the first len bytes of line. The line is read 
until 'RETURN' is pressed at the keyboard. The line is truncated if line 
is not large enough. A newllne or carriage return is not included in line. 

The result returned can take any of the following values: 

spr . ok The read was successful. 

> spr .operation, failed If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.1 and H,2.2). 
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so . read . echo . line 

PROC so. read. echo. line (CHAN OF SP fs, ts, 

INT len, []BYTE line, 
BYTE result) 



As so. read, line, but user input {except newline or carriage return) 
is echoed on the screen. 

so .ask 

PROC so. ask (CHAN OF SP fs, ts, 

VAL []BYTE prompt, replies, 

VAL BOOL display. possible, replies, 

VAL BOOL echo. reply, 

INT reply . nuinber) 

Prompts on the screen for a user response on the keyboard. The prompt 
is specified by the string prompt, and the list of permitted relies by the 
string replies. Only single character responses are permitted, and 
alphabetic characters are nor case sensitive. For example if the permit- 
ted responses are 'Y\ 'N' and 'Q' then the replies string would con- 
tain the characters "YNQ", and 'y'. '^' ^^^ 'q' would also be accepted. 
reply. number indicates which response was typed, numbered from 
zero. " ? " is automatically output at the end of the prompt, 

(f display, possible. replies is TRUE the permitted replies are 
displayed on the screen. If echo. reply is true the user's response 
is displayed. 

The procedure will not return until a valid response has been typed. 
so . read . echo . int 

PROC so. read, echo. int (CHAN OF SP fs, ts, INT n, 

BOOL error) 

Reads a decimal integer typed at the keyboard and displays it on the 
screen. The number must be terminated by 'RETURN". The boolean 
error is set So TRUE if an invalid integer is typed, false othenwise. 
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so * read . echo , int32 

PROC so. read. echo, int 32 (CHAN OF SP fs, ts, 

INT32 n, BOOL error) 

As so. read. echo. int but reads 32-bit numbers. 

so. read. echo. int64 

PROC so. read. echo. int64 {CHAN OF SP fs, ts, 

INT64 n, BOOL error) 

As so. read. echo. int but reads 64-bit numbers, 

so , read . echo . hex . int 

PROC so, read. echo. hex. int (CHAN OF SP fs, ts, 

INT n, BOOL error) 

As so. read, echo, int but reads a number in hexadecimal format. 
Tiie number may be in lower or upper case but must be prefixed with ei- 
ther '#", or '$' which directly indicates a hexadecimal number, or *%', which 
means add mostneg int to the given iiex (using modulo arithmetic). 
For example, on a 32-bit transputer %70 is interpreted as #80000070, 
and on a 16-bit transputer as #807 0. This is useful when specifying 
transputer addresses, which are signed and start at mostneg int. 

so . read . echo . hex , int32 

PROC so, read. echo. hex. int32 <CHAN OF SP fs, ts, 

INT32 n, BOOL error) 

As so. read, echo. hex. int but reads 32-bit numbers. 

so. read. echo. hex, int 64 

PEOC so. read. echo. hex. int 64 (CHAN OF SP fs, ts, 

INT64 n, BOOL error) 

As so . read . echo . hex . int but reads 64-bit numbers. 
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so . read. echo, any .int 

PROC so, read, echo. any. int {CHAN OF SP fs, ts, 

INT n, BOOL error) 

As so. read. echo, int but accepts numbers in either decimal or hex- 
adecimal format. Hexadecimal numbers may be lower or upper case but 
must be prefixed with either '#' or '$' which specifies the number directly, 
or *%', which means add MOSTNEG INT to the given hex (using modulo 
arithmetic). For example, on a 32-bit transputer %70 is interpreted as 
#80000070, and on a 16-bit transputer as #8070. This is useful when 
specifying transputer addresses, which are signed and start at MOSTNEG 

INT, 

so .read. echo, real32 

PROC so. read, echo. real32 (CHAN OF SP fs, ts, 

REAL32 n, BOOL error) 

Reads a real numbertypedatthe keyboard and displays it on the screen. 
The number must conform to OCCam syntax and be terminated by 'RE- 
TURN'. The boolean variable error is set to TRUE if an invalid number 
is typed, false otherwise. 

so. read. echo. real64 

PROC so. read. echo. real64 (CHAN OF SP fs, ts, 

REAL64 n, BOOL error) 

As so. read. echo. real32 but for 64-bit real numbers. 
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1.4.7 Screen output 



Procedure 


Parameter Specifiers 


so. write. char 


CHAN OF SP fs, ts, 
VAL BYTE Char 




so.write.nl 


CHAH OF SP fs, ts 




so . write . string 


CHAN OF SP fs, ts, 
VAL []BYTE string 




so . write . string , nl 


CHAN OF SP fs, ts, 
VAL []BYTE string 




so, write. int 


CHAN OF SP fs, ts, 
VAL INT n, field 




so. write. int32 


CHAN OF SP fs, ts. 






VAL INT32 n, VAL INT 


field 


so. write. int64 


CHAN OF SP fs, ts, 






VAL INT64 n, VAL INT 


field 


so . write , hex , int 


CHAN OF SP fs, ts, 
VAL INT n, width 




so . write .hex . int 32 


CHAN OF SP fs, ts, 






VAL INT32 n, VAL INT 


width 


so . write . hex . int 64 


CHAN OF SP fs, ts. 






VAL INT 64 n, VAL INT 


width 


so, write. real32 


CHAN OF SP fs, ts, 






VAL REAL32 r, VAL IN^I 


' Ip, Dp 


so .write . real64 


CHAN OF SP fs, ts, 






VAL REAL64 r, VAL INI 


' :^Pr Dp 



Procedure definitions 

so . write . char 

PROC so. write. char (CHAN OF SP fs, ts, 

VAL BYTE char) 

Writes the singfe byte char to the screen. 
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so .write.nl 

PROC so, write.nl (CHAN OF SP fs^ ts) 

Writes a newline sequence to the screen. 

so .write . string 

PROC so, write. string (CHAN OF SP fs, ts, 

VAL []EYTE string) 

Writes the string string to the screen. 

so . write . string . nl 

PROC so. write, String.nl (CHAN OF SP fS/ ts^ 

VAL []BYTE string) 

As SO. write. string, but appends a newline sequence to the end 
of the string. 

so. write. int 

PROC so. write. int (CHAN OF SP fs, tS, 
VAL INT n, field) 

Writes the value n (of type int) to the screen as decimal ASCII dig- 
its, padded out with leading spaces and an optional sign to the specified 
field width. If the field width is too small for the number it is widened 
as necessary; a zero value for field specifies minimum width. A neg- 
ative value for field is an error. 

so . write . int3 2 

PROC so. write. int32 (CHAN OF SP fs, ts, 

VAL INT32 n, VAL INT field) 

As so. write, int but for 32-bit integers. 

so, write . int64 

PROC so. write. int 64 (CHAN OF SP fs, ts, 

VAL INT 64 n, VAL INT field) 

As so . write . int but for 64-bit integers. 
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so , write . hex . int 

PROC so. write. hex. int (CHAN OF SP fs, ts, 

VAL INT n, width) 

Writes the value n (of type int) to the screen as hexadecimal ASCII 
digits, preceded by the '#* character. The number of characters printed 
is width + 1 . If width is larger than the size of the number then the 
number is padded with leading ^O's or 'F's as appropriate. If width is 
smaller than the size of the number, the number is truncated, from the 
left» to width digits. A negative value for width is an error. 

so - write . hex . int32 

PROC so. write. hex, int64 (CHAN OF SP fs, ts, 

VAL INT32 n, 
VAL INT width) 

As so. write. hex. int but for 32-bit integers, 

so , write . hex . int 64 

PROC so, write. hex. int 64 (CHAN OF SP fs, ts, 

VAL INT64 n, 
VAL INT width) 

As so. write, hex, int but lor 64-bit integers. 

so .write , real 32 

PROC so. write. real32 (CHAN OF SP fs, ts, 

VAL REAL32 r, 
VAL INT Ip, Dp) 

Writes the value r (of type REAL32) to the screen as ASCII characters 
formatted using ip and Dp as described under real32tostring (see 
section 1.7). 

Note : Due to fixed size internal buffers, this procedure will be Invalid if 
the string representing the real number is longer than 24 characters. If 
this Is a problem, it is suggested you mWe your own procedure to perform 
this function. The procedure should include a buffer set to the required 
size, a call to REAL32tostring, followed by a ca[l to so. write. 
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so . write . real64 

PROC so. write, real64 (CHAN OF SP fs, ts, 

VAL REAI164 r, 
VAIi INT Ip, Dp) 



As so. write *real32 but for 64-bit real numbers. The formatting 
variables ip and Dp are described under rkal32tostring (see sec- 
tion 1.7). 

Note : Due to fixed size interna) buffers, this procedure will be invalid if 
the siring representing the real number is longer than 30 characters. If 
this is a problem, it is suggested you write your own procedure to perform 
this function. The procedure should include a buffer set to the required 
size, a call to REAli64TOSTRlNG, followed by a call to so. write. 



1.4.8 File output 

These routines write characters and strings to a specified stream, usually a file. 
The result returned can take the values spr.ok, spr.notok or 
very rarely > spr. operation. failed. 
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Procedure 


Parameter Specifiers 


so. f write. char 


CS7VN OF SP fs, ts, 




VAL INT32 streamid, 




VAL BYTE char, BYTE result 


so. f write, nl 


CHAN OF SP fs, ts, 




VAL INT32 streamid, 




BYTE result 


so . f write . string 


CHAK OF SP fs, ts, 




VAL IMT32 streamid. 




VAL []BYTE string, BYTE result 


so . f write . string . nl 


CHAN OF SP fs, ts, 




VAL IJJT32 streamid, 




VAL [JBYTE string, BYTE result 


so . f write . int 


CHAK OF SP fs, ts. 




VAL INT32 streamid. 




VAL INT n, field, BYTE result 


so.fwrite.int32 


CHAN OF SP fs, ts, 




V7^ INT32 streamid, 




VAL INT32 n, VAL INT field. 




BYTE result 


so . f write , int€4 


CHAN OF SP fs, ts, 




VAL INT32 streamid. 




VAL INT64 n, VAL INT field, 




BYTE result 


so . f write . hex . int 


CHAN OF SP fs, ts. 




VAL INT32 streamid, 




VAL INT n, width, BYTE result 


so , f write . hex . int32 


CHAN OF SP fs, ts, 




VAL INT32 streamid, n 




VAL INT width, BYTE result 


so . f write . hex . int 64 


CHAN OF SP fs, ts, 




VAL INT32 streamid. 




VAL INT64 n, VJVL INT width, 




BYTE result 


so . f write . real32 


CHAN OF SP fs, ts. 




VAL INT32 streamid. 




VAL REAL32 r, VAL INT Ip, Dp, 




BYTE result 


so . fwrite . real64 


CHAN OF SP fs, ts. 




VAL INT32 streamid. 




VAL REAL64 r, VAL INT Ip, Dp, 




BYTE result 
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Procedure definitions 
so . f write . char 

PROC so. f write. char (CHAH OF SP fs, ts, 

VAL INT32 streamid, 
VAL BYTE char, 
BYTE result) 

Writes a single character to the specified stream. The result spr . notok 
will be returr^ed if the character is not written. 

so. f write, nl 

PROC so.fwrite.nl (CHAN OF SP fs, ts, 
VAL INT32 streamid, 

BYTE result) 

Writes a newline sequence to the specified stream. 

If result takes a value > spr. operation. failed then this de- 
notes a server returned failure, details of which are documented in section 
C.1 . (See also^ section H.2.2}. 

so . f write . string 

PROC so . f write , string (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL []BYTE string, 
BYTE result) 

Writes a string to the specified stream. The result spr. notok will be 
returned if not all the characters are written. 

so . f write . string . nl 

PROC 30.fwrite.string.nl (CHAN OF SP fs, ts, 

VAL 1NT32 streamid, 
VAL []BYTE string, 
BYTE result) 

As so . f write - string, but appends a newline sequence to the end 
of the string. 

The result returned can take any of the following values: 
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spr . notok Not all of the characters were written. 

> spr .operation, failed if result takes a value 

> spr . operation . failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2.2). 

so , f write . int 

PROC so, f write. int (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT n, field, 
BYTE result) 

Writes the value n (of type int) to the specified stream as decimal 
ASCII digits, padded out with leading spaces and an optional sign to the 
specified field width. If the field width is too small for the number 
it is widened as necessary; a zero value for field will give minimum 
width. A negative value for field is an error. 

The result spr. notok will be returned if not all of the digits are written. 

so . f write . int32 

PROC so. f write. int32 (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT32 n, VAL INT field, 
BYTE result) 

As so . f write , int but for 32-bit integers. 

so . f write . int 6 4 

PROC so. f write. int 64 (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT64 n, VAL INT field, 
BYTE result) 

As so . f write . int but for 64-bit integers. 

so . f write . hex . int 

PROC so. f write. hex, int (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT n, width, 
BYTE result) 
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Writes the value n {of type int) to the specified stream as hexadecimal 
ASCII digits preceded by the '#' character. The number of characters 
printed is width + 1 . If width is larger than the size of the number then 
the number is padded with leading 'O's or 'F's as appropriate. If width 
is smaller than the size of the number, then the number is truncated, 
from the left^ to width digits. A negative value for width is an error 

The result spr .notok will be returned if not all the characters are writ- 
ten, 

so . f write . heac . int32 

PROC so. f write. hex. int32 (CHAN OF SP fs, ts, 

VAL INT32 streamid, n 
VAL INT width, 
BYTE result) 

As so . f write . hex . int but for 32-bit integers. 

so . f write . hex . int 64 

PROC so. f write, hex. int 64 {CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT64 Tir 
VAL INT widthf 
BYTE result) 

As so . f write . hex . int but for 64-bit Integers. 

so . f write . real32 

PROC so. f write. real32 (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL REAL32 r, 
VAL INT Ip, Dp^ 
BYTE result) 

Writes the value r (of type REAL32) to the specified stream as 
ASCII characters formatted using ip and Dp as described under 
KEAL32TOSTRING (see section 1.7). 

The result spr . notok will be returned if not all the characters are writ- 
ten. 

Note : Due to fixed size internal buffers, this procedure will be invalid if 
the string representing the real number is longer than 24 characters. If 
this is a problem, it is suggested you write your own procedure to perform 
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this function. The procedure should include a buffer set to the required 
size, a call to Riial32tostring, followed by a call to so. write. 

so.£write.real64 

PROC so. f write. real 64 (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL REAL64 r, 
VAL INT Ipr Dp, 
BYTE result) 



As so. f write. real32 but for 64-bit real numbers. The formatting 
variables ip and Dp are described under REAL32T0STRing (see sec- 
tion 1.7). 

Note : Due to fixed size internal buffers, this procedure will be invalid if 
the siring representing the real number is longer than 30 characters. If 
this is a problem, it is suggested you write your own procedure to perform 
this function. The procedure should include a bufter set to the required 
size, a call to REAii64TOSTRiNG, followed by a call to so .write. 



1.4.9 Miscellaneous commands 

The miscellaneous group includes procedures for: 

• Time and date processing 

• Buffering and multiplexing 
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Time processing 



Procedure 


Parameter Specifiers 


so . time . to , date 


VAL INT32 input. time, 




[so, date. len] INT date 


so . date . to . ascii 


VAL [so.date.len]INT date^ 




VAIi BOOL long. years, 




VAL BOOL days. first, 




[so. time. string, len] BYTE string 


so . time . to . ascii 


VAL INT32 time. 




VAL BOOL long. years, 




VAL BOOL days. first 




[so. time. string. len]BYTE string 


so. today -date 


CHAN OF SP fs, ts. 




[SO. date, len] INT date 


so . today . ascii 


CHAN OF SP fs, ts. 




VAL BOOL long. years. 




VAL BOOL days. first. 




[ so. time. string.len] BYTE string 



so. time -to. date 

PROC so. time. to. date (VAL INT32 input. time, 

[so.date.lenlINT date) 

Converts time (as supplied by so. time) to six integers, stored in the 
date array. The elements of the array are as iollows: 



Element of array 


Data 





Seconds past the minute 


1 


Minutes past the hour 


2 


The hour (24 hour clock) 


3 


The day of the month 


4 


The month (1 to 12) 


5 


The year (4 digits) 
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so .date -to .ascii 

PROC so. date. to. ascii 

(VAL [so,date.len]INT date, 
VAL BOOL long, years, 
VAL BOOL days. fir St, 
[so.time.string.l6n]BYTE string) 

Converts an array of six integers containing the date (as supplied by 
so. time. to. date) into an ASCII string of tlie form: 

HH:MM:SS DD/MfWYYYY 



If long. years is FALSE then year is reduced to two characters, and 
tine last two characters of the year field are padded with spaces. If 
days . first is FALSE then the Ordering of day and month is changed 
(to the U.S. standard). 

so .time .to . ascii 

PROC so. time. to. ascii 

(VAL rNT32 time, 
VAL BOOL long. years, 
VAL BOOL days. first 
[so. time. string. len] BYTE string) 

Converts time (as supplied by so. time) into an ASCJI string, as de- 
scribed for so.date. to. ascii. 

so. today. date 

PROC so, today, date (CHAN OF SP fs, ts, 

[so.date. len] INT date) 

Gives today's date, in local time, as six integers, stored in the date 
array. The format of the array is the same as for so .time .to .date. 
If the date is unavailable all elements in date are set to zero. 

so .today , ascii 

PROC so. today .ascii 

(CHAN OF SP fs, ts, 
VAL BOOL long. years, days, first, 
[so. time. string, lenJBYTE string) 
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Gives today's date, in local time, as an ASCII string. In the same format 
as procedure so.date.to.ascii. If the date is unavailable string 
is filled with spaces. 

Buffers and multiplexors 

This group of procedures are designed to assist with buffering and multiplexing 
data exchange between the program and host. 



Procedure 


Paranneter Specifiers 


so .buffer 


CHAN OF SP £s, ts. 




from, user, to. user. 




CHJ^ OF BOOL stopper 


so . overlapped .buff er 


CHAN OF SP fs. ts, 




from. user, to .user, 




CHAN OF BOOL stopper 


so. multiplexor 


CHAN OF SP fs, ts, 




[]CHAN OF SP 




from. user, 




to. user, 




CHAN OF BOOL stopper 


so. over lapped. multiplexor 


CHAN OF SP fs, ts. 




[]CHAK OF SP 




from, user, 




to. user, 




CHAN OF BOOL stopper. 




[ ] INT queue 


so.pri .multiplexor 


CHAN OF SP fs, ts, 




:]CHAN OF SP 




from* user. 




to. user. 




CHAN OF BOOL stopper 


so . overlapped . pri , multiplexor 


CHAN OF SP fs, ts. 




[]CHAN OF SP 




from* user, 




to. user. 




CHAN OF BOOL stopper. 




[ ] INT queue 
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so -buffer 

PROC so. buffer {CHAN OF SP fs, ts, 

from . user, to . user, 
CHAN OF BOOL stopper) 

This procedure buffers data between the user and the host. It can be 
used by processes on a network to pass data to the host across inter- 
vening processes. It Is terminated by sending either a TRUE or false 
value on the channel stopper. 

so , overlapped . buffer 

PROC SO. overlapped. buffer (CHAN OF SP fs, ts, 

from* user, 
to. user, 
CHAN OF BOOL stopper) 

Sin:;i!ar to so, buffer, but allows many host communications to occur 
simultaneously through a train of processes. This can improve efficiency 
if the communications pass through many processes before reaching the 
sen/er. It is terminated by either a TRUE or FALSE value on the channel 
stopper. 

so .multiplexor 

PROC so. multiplexor (CHAN OF SP fs, ts, 

[]CHAN OF SP from. user, 

to. user, 
CHAN OF BOOL stopper) 

This procedure multiplexes any number of pairs of SP protocol channels 
onto a single pair of SP protocol channels, which may go lo the file server 
or another SP protocol multiplexor (or buffer). It is terminated by sending 
either a true or false value on the channel stopper. For n channels, 
each channel is guaranteed to be able to pass on a message ior every n 
messages that pass through the multiplexor. This is achieved by cycling 
the selection priority from the lowest index of from. user. However, 
stopper always has highest priority. 
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so . overlapped . multiplexor 

PROC so. overlapped. multiplexor 

(CHAN OF SP fs, ts, 
[]CHAK OF SP from. user, to. user, 
CHAN OF BOOL stopper, 
[ 1 INT queue) 

Similar to so. multiplexor, but can pipeline server requests. The 
number of requests than can be pipelined is determined by the size 
of queue, which must provide one word for each request that can be 
pipelined. If SIZE queue is zero then the routine simply waits for in- 
put from stopper. Pipelining improves efficiency if the server requests 
have to pass through many processes on the way to and from the server. 
It is terminated by sending either a true or FALSE value on the channel 
stopper. 

The multiplexing is done in the same cyclic manner as in 
so. multiplexor. stopper has higher priority than any of 
from. user. 

so .pri , multiplexor 

PROC so. pri. multiplexor 

(CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, to. user, 
CHAN OF BOOL stopper) 

As so. multiplexor but the multiplexing is not done in a cydic man- 
ner; rather there is a hierarchy of priorities amongst the channels 
from. user: from. user [i] is of higher priority than from. user 
[ jl.lori < j. Alsostopperisof lower priority than any of from. user. 

so. overlapped. pri. multiplexor 

PROC so. overlapped. pri, multiplexor 
(CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, to. user, 
CHAN OF BOOL stopper, 
[] INT queue) 

As so. over lapped, multiplexor but the multiplexing is done in 
the same prioritized manner as in so, pri, multiplexor, stopper 
has higher priority than any of from. user. 
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1.5 Streamio library 

Library: streamio. lib 

The streamio f/brary contains routines for reading ancf writing to files and to 
tiie terminaf at a higher level of abstraction than the hostio library. The file 
streamio. inc defines the ks and ss protocols and constants used by the 
streamio library routines. The result value from many of the routines in this 
library can take a value > spr . operation . failed which is a server depen- 
dent failure result. It has been left open with the use of > because future server 
implementations may give more failure information back via this byte. Names 
for result values can be found in the fiJe hostio . inc. 

The streamio routines can be classified into three main groups: 

• Stream processes 

• Stream input procedures 

• Stream output procedures. 

Stream fnput and output procedures are used to input and output characters in 
keystream KS and screen stream ss protocols. KS and SS protocols must be 
convened to the server protocol before communicating with the host, 

Stream processes convert streams from keyboard or screen protocol to the 
server protocol SP or to related data structures. They are used to transfer data 
from the stream input and output routines to the host. Stream processes can 
be run as parallel processes serving stream input and output routines called in 
sequential code. For example, the following code clears the screen of a terminal 
supporting ANSI escape sequences: 

CHAN OF ss scrn : 
PAR 

so . scrstream. to , ANSI (f s , ts, scrn) 
SEQ 
s s. goto. xy (scrn, 0, 0} 
as. clear. eos (scrn) 
ss . write* endstream (scrn) 

The key stream and screen stream protocols are identical to those used in the 
IMS D700 Transputer Development System (TDS) and facilitate the porting of 
programs between the TDS and the toolset. 
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1.5.1 Naming conventions 

Procedure names always begin with a prefix derived Irom the first parameter. 
Stream processes, where the SP channel (listed first) is used in combination 
with either the KS or SS protocols, are prefixed with 'so.'. Stream input rou- 
tines, which use only the KS protocol are prefixed with 'ks . ', and stream output 
routines, which use only the ss protocoE, are prefixed with 'ss .'. The single ks 
to ss conversion routine, which uses both protocols, is prefixed with 'ks .'. 



1.5.2 Streann processes 



Procedure 


Parameter Specifiers 


so . keystream . from , kbd 


CHAN OF SP fs, ts, 




CHAK OF KS keys. out. 




CHAN OF BOOL stopper, 




VAL INT ticks. per. poll 


so . keystream. from, file 


CHAN OF SP fs, ts, 




CHAN OF KS keys, out r 




VAL []BYTE filename, 




BYTE result 


so . keystream , from . stdin 


CHAN OF SP fs, ts, 




CHAN OF KS keys. out, 




BYTE result 


ks .keystream. sink 


CHAN OF KS keys 


ks . keystream. to . scrstream 


CHAN OF KS keyboard. 




CHAN OF SS scrn 


ss . scrstream. sink 


CHAN OF SS scrn 


so . scrstream. to . file 


CHAN OF SP fs, ts, 




CHAK OF SS scrn. 




VAL []BYTE filename. 




BYTE result 


so . scrstream , to , stdout 


CHAN OF SP fs, ts, 




CHAN OF SS scrn, 




BYTE result 
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Procedure 


Parameter Specifiers 


ss. scrst ream. to. array 


CHAN OF ss scrn, 




[]BYTE buffer 


ss . scrstream . from , array 


CEIAN OF SS scrn. 




VAL []BYTE buffer 


ss , scrstream . fan , out 


CHAN OF SS scrn. 




screen. outl, 




screen. out2 


ss . scrstream. copy 


CHAN OF SS scrn.in. 




scrn.out 


so . scrstream . to . ANSI 


CHAN OF SP fs, ts. 




CHAN OF SS scrn 


so . scrstream . to . TVI 92 


CHAN OF SP fs, ts, 




CHAN OF SS scrn 


ss .scrstream. multiplexor 


t]CHAN OF SS screen. in. 




CHAN OF SS screen. out. 




CHAN OF INT stopper 



Procedure definitions 

so . keystream . from . kbd 

PROC so, keystream. from. kbd 

(CHAN OF SP fs, ts, 
CHAN OF KS keys. out, 
CHAN OF BOOL stopper, 
VAL INT ticks. per. poll) 

Reads characters from the keyboard and outputs them one at a time 
as integers on the channel keys .out. tt is terminated by sending ei- 
ther a TRUE or FALSE on the boolean channel stopper. The pro- 
cedure polls the keyboard at an interval determined by the value of 
ticks. per, poll, in transputer clock cycles, unless keys are avail- 
able, in which case they are read at full speed. It is an error if 
ticks .per , poll is less than or equal to zero. 

After FALSE is sent on the channel stopper the procedure sends the 
negative value ft . terminated on keys . out to mark the end of the 
file. 
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so.keystream. from. file 

PROC so,keystream. from. file 

(CHAN OF SP fs, ts, 
CHAN OF KS keys. out, 
VAL []BYTE filename, 
BYTE result) 

Reads lines from the specified text file and outputs them on keys .out. 
Terminates automatically on error or when it has reached the end of 
the file and all the characters have been output on the keys. out 
channel- A '*c' is output to terminate a text line. The negative value 
ft .terminated is sent on the channel keys, out to mark the end 
of the file. The result returned can take any of the foSlowing values: 



spr . ok 

spr .bad. packet . size 



The operation was successful. 
Filename too large i.e. 
SIZE filename > 
5p .max . openname . size. 
Null file name. 



spr . bad . name 

> spr. operation. failed The open failed or reading the file 

failed. If result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 

so .keys t ream. from, stdin 

PROC so, keystream, from. stdin 

{CHAN OF SP fs, ts, 

CHAN OF KS keys. out, 

BYTE result) 

As so.keystream. from. file, but reads from the standard input 
stream. The standard input stream is normally assigned to the keyboard, 
but can be redirected by the host operating system. End of file from 
keyboard will terminate this routine. The result returned may take any of 
the following values: 
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spr.ok The operation was successful. 

> spr. operation, failed Reading standard input failed. If 

result takes a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C,1 and H.2.2), 

ks . keystream . sink 

PROC ks, key stream. sink (CHAN OF KS keys) 

Reads word length quantities until ft .terminated is received, then 
terminates. 

ks , keyst ream . to . scrstream 

PROC ks .keyst ream. to. scrstream (CHAN OF KS 

keyboard, 
CHAN OF SS scrn) 

Converts key stream protocol to screen stream protocol. The value 
ft .terminated on keyboard terminates the procedure. 

SS . scrstream. sink 

PROC ss .scrstream. sink (CHAN OF SS scrn) 

Reads screen stream protocol and ignores It except for the stream ter- 
minator from ss -write . endstream which terminates the procedure. 

so . scrstream . to . file 

PROC so. scrstream. to. file (CHAM OF SP fs, ts, 

CHAN OF SS scrn, 
VAL []BYTE filename, 
BYTE result) 

Creates a new file with the specified name and writes the data sent on 
channel scrn to it. The scrn channel uses the screen stream pro- 
tocof which is used by all the stream output library routines (and is the 
same as the Inmos TDS screen stream protocol). It terminates on receipt 
of the stream terminator from ss .write. ends tream^ or on an error 
condition. The result returned can take any of the following values: 
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spr . ok 

spr. bad. packet . size 

spr .bad. name 



The data sent on scrn was success- 
fully written to the file. 

Filename 

too large i.e. SIZE filename > 

sp . max . openname . size. 

Nuli filename. 

> spr. operation. failed If result takes a value 

> spr . operation . failed 

then this denotes a server returned 
failure. (See sections C.1 and H. 2. 2). 

!( used in conjunction with scscrstream.fan.out this procedure 
may be used to file a copy of everything sent to the screen. 

so . scrstream . to . stdout 

PROC so. scrstream. to. stdout (CHAN OF SP fs, ts, 

CHAK OF SS scrn, 
BYTE result) 

Performs the same operation as so. scrstream, to. file, but writes 
to the standard output stream. The standard output stream goes to the 
screen, but can be redirected to a file by the host operating system. The 
result returned can take any of the following values: 



spr , ok 

> spr, operation. failed 



The data sent on scrn was success- 
fully written to standard output. 
If result lakes a value 
> spr -Operation. failed 

then this denotes a server returned 
failure. (See sections C.1 and H.2.2). 



ss .scrstream. to. array 

PROC ss. scrstream. to. array 



(CHJ^N OF SS scrn; 
[]BYTE buffer) 



Buffers a screen stream whose total size does not exceed the capacity 
of buffer, for debugging purposes or subsequent onward transmission 
using so. scrstream. from, array. The procedure terminates on 
receipt of the stream terminator from ss .write . endstream. 
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ss .scrstream, from. array 

PROC S3 .scrstream. from. array (CHAN OF SS scrn, 

VAL []BYTE buffer) 

Regenerates a screen stream buffered in buffer by a previous cafi of 
so, scrstream.to.array, Terminates when all buffered data has 
been sent. 

S3 .scrstream. fan. out 

PROC ss. scrstream, fan. out 

(CHAK OF SS scrn, 

screen. out 1^ 
screen. out2) 

Sends copies of everything received on the input channel scrn to two 

output channels. The procedure terminates on receipt of the stream 
terminator from ss. write. endst ream without passing on the termi- 
nator. 

SS . scrstream . copy 

PROC SS, scrstream. copy (CHAN OF SS scrn, in, 

scrn -out) 

Copies screen stream protocol input 

on scrn. in to scrn. out. Terminates on receipt of the endstream 
terminator from ss. write, endstream, which is not passed on. 

so . scrstream , to . ANS I 

PROC so, scrstream. to. ANSI (CHAN OF SP fa, ts^ 

CHAN OF SS scrn) 

Converts screen stream protocol into a stream of BYTEs according to 
the requirements of ANSI terminal screen protocol. Not all of the screen 
stream commands are supported. 

The following tags are ignored: 

St. ins. char, st. reset, st .terminate, st.help, 
St .initialise, st. key. raw, st . key .cooked, 
st, release, st. claim. 

The procedure terminates on receipt of the stream terminator from 
SS . write . endstream. 
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so , scrstream. to . TVI920 

PROC so.scrstreara,to.TVI920 (CHAN OF SP fs, ts, 

CHAN OF SS scrn) 



Converts screen stream protocol into a stream of BYTEs according to the 
requirements of TVI 920 (and compatible) terminals. Not all of the screen 
stream commands are supported. The following tags are ignored: 

St. reset, st -terminate^ st.help, st .initialise, 
St, key, raw, st . key . cooked, st. release, st. claim. 

The procedure terminates on receipt of the stream terminator from 
SS . write , endstream. 

ss . scrstream. multiplexor 

PROC SS. scrstream. multiplexor 

(nCHAN OF SS screen. in, 
CHAN OF SS screen, out, 
CHAN OF INT Stopper) 



This procedure multiplexes up to 256 screen stream channels onto a 
single screen stream channel. Each change of input channel directs 
output to the next line of the screen, and each such line is annotated at 
the left with the array index of the channel used followed by '>'. The tag 
st . endstream is ignored. The procedure is terminated by the receipt 
of any integer on the channel stopper. For n channels, each channel 
is guaranteed to be able to pass on a message for every n messages 
that pass through the multiplexor. This is achieved by cycling from the 
lowest index of screen . in. However, stopper always has highest 
priority. 
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1.5.3 Stream input 

These routines read characters and strings from tlie input stream, in KS protocol. 



Procedure 


Parameter Specifiers 


ks .read. char 


CHAW OF KS source, INT char 




ks .read. line 


CHAN OF KS source^ INT len, 
I] BYTE line, INT char 




ks .read.int 


CHAN OF KS source, 
INT number, char 




ks.read,int64 


CHAN OF KS source, 
INT64 number, INT char 




ks.read.real32 


CHAN OF KS source, 
REAL32 number, INT char 




ks,read.real64 


CHAN OF KS source, 
REAL64 number, IKT char 





Procedure definitions 

ks .read. char 

PROC ks. read. char <CHAN OF KS source, INT char) 
Returns in char the next word length quantity from source, 

ks .read. line 

PROC ks. read. line (CHAN OF KS source, INT len, 

[]BYTE line, INT char) 

Reads text Into the array line up to but excluding ' *c' , or up to and 
excluding any error code. Any ^*n' encountered is thrown away, len 
gives the number of characters in line. If there is an error its code is 
returned as char, otherwise the value of char will be int '*c'. If 
the array is filled before a '*c' is encountered ail further characters are 
ignored. 
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ks .read.int 

PROC ks,read.int (CHAU OF KS source, 
INT number, char) 

Skips input up to a digit, #, + or -, then reads a sequence of digits to 
the first non-digit, returned as char, and converts the digits to an integer 
in nuntber. char must be initialised to the first character of the input. 
If the first significant character is a ' #' then a hexadecimal number is 
input, thereby allowing the user the option of which number base to use. 
The hexadecimal may be in upper or lower case, char is returned as 
ft . number . error if the number overflows the INT range. 

ks .read.int64 

PROC ks.read.int€4 (CHAN OF KS source, 

INT 64 nuinber, INT char) 

As ks . read . int, but for 64-bit integers. 

ks . read . real32 

PROC ks.read.real32 (CHAN OF KS source, 

REAL32 number, INT char) 

Skips input up to a digit, + or -, then reads a sequence of digits with 
optional decimal point and exponent) up to the first invalid character, re- 
turned as char. Converts the digits to a floating point value in number, 
char must be initialised to the first character of the input. If there is 
an error in the syntax of the real, if it is ± infinity, or if more than 24 
characters read then char is returned as ft. number. error. 

ks .read, real 64 

PROC ks.read.real64 (CHAN OF KS source, 

REAL64 number, INT char) 

As ks*read.real32. but for 64'bit real numbers. Allows for reading 
up to 30 characters. 
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1.5.4 Stream output 

These routines write text, numbers and screen control codes to an output stream 
[n SS protocol. 



Procedure 


Parameter Specifiers 




SS .write. char 


CHAN OF SS scrn, 
VAL BYTE char 




SS , write.nl 


CHAN OF SS scrn 




SS . write . string 


CHAN OF SS scrn, 
VAL []BYTE str 




SS . write . endstream 


CHAN OF SS scrn 




SS . write . text , line 


CHAN OF SS scrn, 
VAL [IBYTE Str 




SS . write. int 


CHAN OF SS scrn, 

VAL INT number, field 




3S . write. int64 


CHAN OF SS scrn, 
VAL INT 64 number, 
VAL INT field 




SS .write. hex. int 


CHAN OF SS scrn, 

VAL INT nurnber, field 




SS .write. hex. int64 


CHAN OF SS scrn, 
VAL INT64 number, 
VAL INT field 
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Procedure 


Parameter Specifiers 




ss , write . real32 


CHAN OF ss scrn, 
VAL REAL32 mrniber, 
VAL INT Ip, Dp 




ss . write . real 64 


rH?VN OF SS scrn, 
VAL REAL64 number, 
VAIi INT Ip, Dp 




ss , goto - xy 


CHAN OF SS scrn, 
VAL IMT X, y 




ss, clear .eol 


CHAN OF SS scrn 




ss. clear .eos 


CHAN OF SS scrn 




ss^beep 


CHAN OF SS scrn 




ss .up 


CHAN OF SS scrn 




as . down 


CHAN OF SS scrn 




ss.left 


CHAN OF SS scrn 




ss . right 


CHAN OF SS scrn 




ss .insert .char 


CHAN OF SS scrn, VAL BYTE ch 


ss. delete. chr 


CHAN OF SS scrn 




ss, delete. chl 


CHAN OF SS scrn 




ss , ins . line 


CHAN OF SS scrn 




ss. del. line 


CHAN OF SS scrn 





Procedure definitions 

ss .write. char 

PROC ss. write. char (CHAN OF SS scrn, 

VAL BYTE char) 

Sends the ASCII value char on scrn, in scrstream protocol, to the 
current position in the output line. 

ss .write.nl 

PROC ss.write.nl (CHAN OF SS scrn) 

Sends "*c*n" to scrn. 
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ss .write . string 

PROC ss. write. string (CHAN OF SS scrn, 

VAL[]ByTE str) 

Sends all characters in str to scrn. 
33 . write . endstream 

PROC ss.write.endstream (CHAN OF SS scrn) 

Sends a special stream terminator value to scrn. 
SS . write , text . line 

PROC SS. write. text. line (CHAN OF SS scrn, 

VAL []BYTE str) 

Sends all of str to scrn ensuring that, whether or not the last character 
of str is '*c', the last two characters sent are "*c*n". 

ss .write. int 

PROC SS. write. int (CHAN OF SS scrn, 

VAL INT number, field) 

Converts number into a sequence of ASCII decimal digits padded out 
with leadtng spaces and an optional sign to the specified field width 
if necessary. If the number cannot be represented in field characters 
it is widened as necessary, a zero value for field will give minimum 
width. The converted number is sent to scrn. A negative value for 
field is an error. 

ss .write, int 64 

PROC ss. write. int 64 (CHAN OF SS scrn, 

VAL INT64 number, 
VAL IHT field) 

As ss .write . int but for 64-bit integers. 
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ss . writie . hex . int: 

PROC ss .write, hex, int (CHAN OF SS scrn, 

VAL INT number, field) 

Converts number into a sequence of ASCII hexadecimal digits, using 
upper case letters, preceded by '#'. The total number of characters 
sent is always field + 1, padding out with '0' or 'F' on the left if 
necessary. The number is tnjncated at the left if the field is too narrow, 
thereby allowing the less significant part of any number to be printed. 
The converted number is sent to scrn. A negative value for field is 
an error. 

ss. write. hex. int 64 

PROC ss. write, hex. int64 (CHAN OF SS scrn, 

VAL I NT 64 number , 
VAL INT field) 

As 3 3 .write . hex . int but for 64-bit integer vaEues. 

ss. write. real32 

PROC ss. write. real32 (CHAN OF SS scrn, 

VAL REAL32 number, 
VAL INT Ip/ Dp) 

Converts number into an ASCII string formatted using Ip and Dp, as de- 
scribed for REAL32T0STRING, (see section 1.7). The converted num- 
ber is sent to scrn. !f the fornfiatted form of number is larger than 24 
characters then this procedure acts as an invalid process. 

ss . write. real64 

PROC ss. write. real64 (CHAN OF SS scrn, 

VAL REAL64 number, 
VAL INT Ip, Dp) 

As tor ss . write. real32 but for 64-bit real values. See section 1.7, 
REAL32TOSTRING fof the details of the formatting effect of ip and Dp. 
If the formatted form of number is larger than 30 characters then this 
procedure acts as an invalid process. 
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ss .goto . xy 

PROC ss.gotcxy (CHAN OF SS scrn, VAL INT x, y} 

Sends the cursor to screen position (x,y). The origin (0,0) is at tine top 
left corner of the screen. 

S3. clear .eol 

PROC ss, clear. eol (CHAN OF SS scrn) 

Clears screen from the cursor position to the end of the current line. 

SS .clear .eos 

PROC S3, clear, eos (CHAM OF SS scrn) 

Clears screen from the cursor position to the end of the current line and 
all lines below. 

SS .beep 

PROC ss.beep (CHAN OF SS scrn) 

Sends a bell code to the terminal. 
SS .up 

PROC ss.up (CHAN OF SS scrn) 

Sends a command to the terminal to move the cursor one line up the 
screen. 

ss .down 

PROC SS.down (CHAN OF SS scrn) 

Sends a command to the terminai to move the cursor one line dovi^n the 

screen. 

ss -left 

PROC ss.left {CHAN OF SS scrn) 

Sends a command to the terminal to move the cursor one place left. 
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ss .right 

PROC ss. right (CHAN OP SS scrn) 

Sends a command to the terminal to move the cursor one place right. 

ss , insert . char 

PROC ss* insert. char (CHAN OF SS scrn, 

VAL BYTE ch) 

Sends a command to the terminal to move the character at the cursor 
and all those to the right of it one place to the right and inserts char at 
the cursor. The cursor moves one place right. 

ss. delete. chr 

PROC ss, delete. chr (CHAN OF SS scrn) 

Sends a command to the terminal to delete the character at the cursor 
and move the rest ot the line one place to the left. The cursor does not 
move. 

ss . delete, chl 

PROC ss. delete. chl (CHAN OF SS scrn) 

Sends a command to the terminal to delete the character to the left of 
the cursor and move the rest of the line one place to the left, The cursor 
also moves one place left. 

ss .ins. line 

PROC ss. ins. line (CHAN OF SS scrn) 

Sends a command to the terminal to move all lines below the current line 
down one line on the screen, losing the bottom line. The current line 
becomes blank. 

ss .del . line 

PROC ss. del. line (CHAN OF SS scrn) 

Sends a command to the terminal to delete the current line and move all 
lines betow it up one line. The bottom Jine becomes blank. 
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1.6 String handling library 

Library: string, lib 

This library contains functions and procedures for handling strings and scanning 
lines of text. They assist with the manipulation of character strings such as 
names, commands, and keyboard responses. 

The library provides routines for: 

• Identifying characters 

• Comparing strings 

• Searching strings 

• Editing strings 

• Scanning lines of text 



Result 


Function 


Parameter Specifiers 


BOOL 


is . in. range 


VAL BYTE char, bottom, 
top 


BOOL 


is . upper 


VAL BYTE char 


BOOL 


is. lower 


VAL BYTE char 


BOOL 


is .digit 


VAL BYTE Char 


BOOL 


is .hex. digit 


VAL BYTE char 


BOOL 


is. id, char 


VAL BYTE Char 


INT 


compare . strings 


VAL []BYTE strl, str2 


BOOL 


eqstr 


VAL []BYTE sl,s2 


INT 


string. pos 


VAL [IBYTE search, str 


INT 


char.pos 


VAL BYTE search, 
VAL []BYTE str 


INT, BYTE 


search. match 


VAL HBYTE possibles, str 


INT, BYTE 


s earch . no . match 


VAL []BYTE possibles, Str 
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Procedure 



str, shift 

delete . string 

insert .string 

to. upper. case 
to . lower , case 



Parameter Specifiers 



append - char 
appends text 
append . int 
append. int €4 
append . hex . int 
append . hex . int 6 4 

append . real32 

append . rea 164 



[]BYTE str, 

VAL INT start, len, shift, 

BOOL not , done 

INT len, 11 BYTE Str, 
VAL INT start, size, 
BOOL not. done 

VAL []BYTE new. Str, 

INT len, [IBYTE str, 

VAL INT start, BOOL not. done 

[]BYTE str 

[]BYTE str 



INT len, []BYTE str, 
VAL BYTE char 

INT len, t]BYTE str, 
VAL []BYTE text 

INT len, []BYTE str, 
VAL INT number, field 

INT len, []BYTE str, 

VAL INT64 number, VSi INT field 

INT len, []BYTE Str, 
VAL INT number, field 

INT len, [JBYTE str, 
VAL INT64 number, 
VAL INT width 

INT len, []BYTE str, 
VAL REALS 2 number, 
VAL INT Ip, Dp 

INT len, []BYTE str, 
VAL REAL64 number, 
VAL INT Ip, Dp 
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Procedure 


Parameter Specifiers 


next . word . from , line 
next . int . from . line 


VAIi []EYTE line, 

INT ptr, len, 

tlBYTE word, BOOL ok 

VAL []BYTE line, 

INT ptr, number, BOOL ok 



1.6,1 Character identification 

is . in . range 

BOOL FDNCTION is, in. range (VAL BYTE char, bottom, 

top) 

Returns true if the value of char is in tine range defined by bottom 
and top tncJusive. 

is . upper 

BOOL FUNCTION is, upper (VAL BYTE char) 

Returns TRUE if char Is an ASCII upper case ietter. 
is . lower 

BOOL FUNCTION is * lower (VAL BYTE char} 

Returns true if char is an ASCII iower case letter, 
is .digit 

BOOL FUNCTION is . digit (VAL BYTE char) 

Returns TRUE if char is an ASCII decimai digit, 
is -hex, digit 

BOOL FUNCTION is. hex. digit (VAL BYTE char) 

Returns true If char Is an ASCII hexadecfmal digit. Upper or lower 
case letters A-F are allowed. 
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is. id, char 

BOOL FUNCTION is. id. char (VAL BYTE char) 

Returns true if char is an ASCII character which can be part of an 
Occam name. 

1.6.2 String comparison 

These two procedures allow strings to be compared for order or for equality. 

compare . strings 

INT FUNCTION compare. strings (VAL []BYTE strl, 

Str2) 

This general purpose ordering function compares two strings according 
to the lexicographic ordering standard. (Lexicographic ordering is the 
ordering used in dictionaries etc., using the ASCII values of the bytes). 
It returns one of the 5 results 0, 1 , -1, 2, -2 as follows. 

The strings are exactly the same in length and content. 

1 str2 is a leading substring of strl 
-1 strl is a leading substring of str2 

2 strl Is lexicographically later than str2 
-2 str2 Is lexicographically later than strl 

So if s is 'abed': 

compare . strings ("abc", [s FROM FOR 3]) = 

compare. strings ("abc", [a FROM FOR 2]) - ^ 

compare, strings ("abc", s) = -1 

compare , strings < "be" , s) =2 

compare . strings ( " a4 " / s ) = -2 

eqstr 

BOOL FUNCTION eqstr (VAL []BYTE sl,s2) 

This is an optimised test for siring equality. It returns TRUE if the two 
strings are the same size and have the same contents, false othenft^ise, 
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1.6.3 String searching 

These procedures allow a string to be searched for a match with a single byte 
or a string of bytes, for a byte whJch is one oJ a set of possible bytes, or for a 
byte which is not one of a set of bytes. Searches insensitive to alphabetic c^e 
should use to. upper. case or to. lower. case on both operands before 
using these procedures. 

string . pes 

INT FUNCTION string. pes (VAL []BYTE search, str) 

Returns the position in str of the first occurrence of a substring which 
exactly matches search. Returns -1 if there is no such match. 

char .pos 

INT FUNCTION char.pos (VSi BYTE search, 

VAL []BYTE str) 

Returns the position in str of the first occurrence of the byte search. 
Returns -1 if there is no such byte. 

search. match 

INT, BYTE FUNCTION search, match 

(VAL []BYTE possibles, str) 

Searches str for any one of the bytes in the array possibles, if one 
is found its index and identity are returned as results. If none is found 
then -1,255(BYTE) are returned. 

search . no . match 

INT, BYTE FUNCTION search, no .match 

(VAL []BYTE possibles, str) 

Searches str for a byte which does not match any one of the bytes in 
the array possibles. If one is found its index and identity are returned 
as results. If none is found then -1,255(BYTE) are returned. 

1.6-4 String editing 

These procedures allow strings to be edited. The string to be edited is stored 
in an array which may contain unused space. The editing operations supported 
are: deletion of a number of characters and the closing of the gap created; 
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insertion of a new string starting at any position within a string, which creates a 
gap of the necessary size. 

These two operations are supported by a lower level procedure for shifting a 
consecutive substring left or right within the array. The lower level procedure 
does exhaustive tests against overflow. 

str, shift 

PROC str. shift {[]BYTE str, VAL INT start, 
len, shift, BOOL not. done) 

Takes a substring [str from start FOR len], and copies it to a 
position shift ptaces to the right. Any implied actions involving bytes 
outside the string are not performed and cause the error flag not .done 
to be set TRUE. Negative values of shift cause leftward moves. 

delete. string 

PROC delete. string (INT len, []BYTE str, 

VAL INT start/ size, 
BOOL not . done ) 

Deletes size bytes from the string str starting at str [start] . 
There are Initially len significant characters in str and it is decremented 
appropriately. If start is outside the string, or start + size is greater 
than len, then no action occurs and not , done is set troe. 

insert , string 

PROC insert ^string (VAL []BYTE new.str, INT len, 

[]BYTE str, VAL INT start, 
BOOL not . done ) 

Creates a gap in str after str [stairt] and copies the string 
new, str into it. There are initially len significant characters in str and 
len is incremented by the length of new. str inserted. Any overflow 
oJ the declared SIZE of str results in truncation at the right and setting 
not. done to TRUE, This procedure may be used for simple concate- 
nation on the right by setting start - len or on the lefl by setting 
start = 0. This method of concatenation differs from that using the 
append, procedures in that it can never cause the program to stop. 
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to . upper . case 

PROC to. upper. case (IJBYTE str) 

Converts all alphabetic characters in str to upper case. 

to , lower , case 

PROC to. lower, case ([]BYTE atr) 

Converts all alphabetic characters in str to lower case. 

append, char 

PROC append. char (INT len, []BYTE str, 
VAL BYTE char) 

Writes a byte char into the array str at str[len]. len is incre- 
mented by 1. Behaves like STOP if the array overflows. 

append. text 

PROC append. text (INT len, []BYTE str, 
VAL []BYTE text) 

Writes a string text into the array str, starting at str [len] and 
computing a new value for len. Behaves like stop if the array overflows. 

append . int 

PROC append. int (INT len, []BYTE str, 

VAL INT number, field) 

Converts number into a sequence of ASCII decinna] digits padded out 
with leading spaces and an optional sign to the specified field width 
if necessary. If the number cannot be represented in field characters 
it is widened as necessary. A zero value for field will give minimum 
width. The converted number is written into the array str starting at 
str [len] and len is incremented. Behaves like stop if the array 
overflows or if field < 0. 
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append. int64 

PROC append. int64 {INT len, []BYTE str, 
VAL INT64 number, 
VAL INT field) 

As append, int but for 64-bit integers. 

append . hex . int 

PROC append. hex. int (INT len, [IBYTE str, 

VAL INT number, width) 

Converts number into a sequence of ASCII hexadecimal digits, using 
upper case letters, preceded by '#'. The total number of characters sent 
is always width+l, padding out with 'C or 'F' on the left if necessary. 
The number is truncated at the left if the field is too narrow, thereby allow- 
ing the less significant part of any number to be printed. The converted 
number is written into the array str starting at str lien] and len is 
incremented. Behaves like STOP if the array overflows or if width < 0. 

append, hex. int 6 4 

PROC append. hex, int 6 4 (INT len, []BYTE str, 

VAL INT64 number, 
VAL INT width) 

As append. hex. int but for 64-bit integers. 

append. real32 

PROC append. real32 (INT len, []BYTE str, 

VAL REAL32 number, 
VAL INT Ip, Dp) 

Converts number Into a sequence of ASCII characters formatted using 
ip and Dp as described under real32TOSTRING (see section 1.7). 

The converted number is written into the array str starting at str [len] 
and len Is incremented. Behaves like STOP if the array overflows. 
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append. real64 

PROC append. real64 (INT len, []BYTE str, 

VAL re:aIi64 number, 
VAL INT Jp, Dp) 

As append , reai32, but for 64-bit real values. The formatting variables 
ip and Dp are described under real32tostring, (see section 1.7), 

1.6.5 Line parsing 

Depending on the initial value of the variable ok these two procedures either 
read a line serially, returning the next word and next integer respectively, or the 
procedures act almost like a skip (see beJow). The user should initialise the 
variable ok as appropriate. 

next .word, from. line 

PROC next. word. from. line (VAL []BYTE line^ 

INT ptr, len, 
[]BYTE word, 
BOOL ok) 

If Ok is passed in as true, on entry to the procedure, skips leading 
spaces and horizontat tabs and reads the next word from the string line. 
The value of ptr is the starting point of the search. A word continues 
until a space or lab or the end of the string line is encountered. 

If the end of the string is reached without finding a word, the boolean ok 
is set to FALSE, and len is 0. If a word is found but is too large for 
word, then ok is set to FALSE, but len will be the length of the word 
that was found; otherwise the found word will be in the first len bytes of 
word. 

The index ptr is updated to be that of the space or tab immediately after 
the found word, or is SIZE line. 

If ok is passed in as false, len is set to 0, ptr and ok remain 
unchanged, and word is undefined. 
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next . int . from . line 

PROC next. int. from, line (VAL []BYTE line, 

INT ptr, number, 
BOOL ok) 

if ok is passed in as TRUE, on entry to the procedure, skips leading 
spaces and horizontal tabs and reads the next integer from the string 
line. The value of ptr is the starting point of the search. The in- 
teger is considered lo start with the first non-space, non-tab character 
found and continues until a space or tab or the end of the string line 
is encountered. 

if the first sequence of non-space, non-tab characters does not exist, 
does not form an integer, or forms an integer that overflows the INT 
range then ok is set to false, and number is undefined; otherwise ok 
remains true, and number is the integer read. A + or ■ may be the 
first character of the integer. 

The index ptr is updated to be that of the space or tab immediately after 
the found integer, or is SIZE line. 

If ok is passed in as false, then ptr and ok remain unchanged, and 
number is undefined 



1,7 Type conversion library 

Library: convert, lib 

This library contains procedures for converting numeric variables to strings and 
vice versa. 

String to numeric conversions return two results, the converted value and a 
boolean error indication. Numeric to string conversions return the converted 
string and an integer which represents the number of significant characters writ- 
ten into the string. 
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Procedure 


Parameter Specifiers 


INTTOSTRING 


INT len, I] BYTE string, 


VAL INT n 


INT16T0STRING 


INT len, []BYTE string, 


VAL INT16 n 


INT32T0STRING 


INT len, []BYTE string, 


VAL INT32 n 


INT64TOSTRING 


INT len, []BYTE string, 


VAL INT64 n 


HEXTOSTRING 


INT len, [JBYTE string, 


VAL INT n 


HEX16TOSTRING 


INT len, []BYTE String, 


VAL INT16 n 


HEX32TOSTRING 


INT len, []BYTE string, 


VAL INT32 n 


HEX64TOSTRING 


INT len, []BYTE string. 


VAL INT64 n 


REAL32TOSTRING 


INT len, []BYTE string, 






VAL REAL32 X, VAL INT Ip, Dp 


REAL64TOSTRING 


XNT len, []BYTE String, 
VAL INT Ip, Dp 


VAL REAL64 X, 


BOOLTOSTRING 


INT len, []BYTE String, 


VAL BOOL b 


STRINGTOINT 


BOOL Error, INT n, VAL 


[]BYTE string 


STRINGT0INT16 


BOOL Error, INT 16 IX, 
VAL []BYTE string 




STRINGTOINT32 


BOOL Error, 1NT32 n, 
VAL []BYTE string 




STRINGTOINT64 


BOOL Error, INT64 n, 
VAL []BYTE String 




STRItlGTOHEX 


BOOL Error, INT n, VAL 


[ IBYTE string 


STRINGT0HEX16 


BOOL Error, INT 16 n, 
VAL [IBYTE String 




STRIHGT0HEX32 


BOOL Error, INT32 n, 
VAL [IBYTE String 




STRINGTOHEX64 


BOOL Error, INT 6 4 n, 
VAL I] BYTE String 




STRINGTOREAL32 


BOOL Error, REAL32 X, 
VAL []BYTE string 




STRINGTOREAL64 


BOOL Error, REAL64 X, 
VAL []BYTE string 




STRINGTOBOOL 


BOOL Error, b, VAL []BYTE string 



72 TDS 276 02 



March 1991 



1 .7 Type conversion library 135 

1.7.1 Procedure definitions 

INTTOSTRING 

PROC INTTOSTRING (INT ien, [jBlfTE string, 
VAL INT n) 

Converts an integer value to a string. The procedure returns the dec- 
imai representation of n in string and the number of characters in 
the representation, in len. If string is not iong enough to hold the 
representation then this routine acts as an invalid process. 

Simitar proceduresare provided for the types INTI 6, INT32 and INT64. 

INT16TOSTRING 

PROC INT16T0STRING (INT len, []BYTE string, 

VAL INT16 n) 

As INTTOSTRING but for 16-bit inlegers. 

INT32TOSTRING 

PROC INT32TOSTRING (INT len, []BYTE String, 

VAL INT32 n) 

As INTTOSTRING but for 32-blt integers. 

INT64TOSTRING 

PROC INT64TOSTRING (INT len, I]BYTE string, 

VAL INT64 n) 

As INTTOSTRING but for 64-bit integers. 

HEXTOSTRING 

PROC HEXTOSTRING (INT len, [JBYTE string, 
VAL INT n) 

The procedure returns the hexadecimal representation of n in string 
and the number of characters In the representation, in len. Alt the words 
of n, (in 4-bit wide word lenghts) are output so that leading zeroes are 
included. The number of characters will be the number of bits in an INT 
divided by four. A '#' is not output by the hextostring procedure. If 
string Is not long enough to hold the representalion then this routine 
acts as an invalid process, 

72 TDS 276 02 March 1991 



136 The Occam libraries 

Similar procedures are provided for the types HEX16. HEX32 and HEX64. 

HEX16TOSTRING 

PROC HEX16T0STRING (INT len, [JBYTE string, 

VAL INT16 n) 

As HEXTOSTRING but for 16'bit integers, 

HEX32TOSTRING 

PROC HEX32TOSTRING (INT len, [JBYTE string, 

VAL INT32 n) 

As HEXTOSTRING but for 32-bit integers. 

HEX64TOSTRING 

PROC HEX64TOSTRING (INT len, [JBYTE string, 

VAL INT64 n) 

As HEXTOSTRING but for 64-bit integers. 

REAL32T0STRING 

PROC REAL32T0STRING (INT len, [ ] BYTE string, 

VAL REAL32 X, 
VAL INT Ip, Dp) 

Converts a 32-bit real number (represer>ted in single precision IEEE for- 
mat) to a string of ASCII characters, len is the number of characters 
(BYTES) of string used for the formatted decimal representation of fhe 
number. (The following description applies to and notes the differences 
between this procedure and real64tostring). 

Depending on the value of x and the two formatting variables ip and Dp 
the procedure will use either a fixed or exponential format for the output 
string. These formats are defined as follows: 
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Fixed : First, either a minus sign or space (an explicit plus 

sign is not used), followed by a fraction in the form 
<djgits> . <digits>. Padding spaces are added to 
the left of the sign indicator, as necessary. (Ip gives 
the number of places before the point and Dp the 
number of places after the point). 

Exponential : First, either a minus sign or space (again, an explicit 
plus sign is not used), followed by a fraction in the 
form <d]git> . <dlgils>, the exponential symbol (E), 
the sign of the exponent (explicitly plus or minus), then 
the exponent, which is two digits for a REAL32 and 
three digits for a REAL64. (Dp gives the number of 
digits in the fraction (1 before the decimal point and 
the others after)). 

Possible combinations of ip and Dp fall into three categories, described 
below. Note the term 'Free format' means that the procedure may adopt 
either fixed or exponential format, depending on the actual value of x. 

1 ifXp=0, Dp=0, then free format is adopted. Exponential format 
is used if the absolute value of X is less than 10""^, but non- 
zero, or greater than 10^ (forREAL32), or greater than 10^^ (for 
REAi,64); otherwise fixed format is used. 

The vaEue of len is dependent on the actual value of x with 
trailing zeroes suppressed. The maximum length of the result 
is 15 or 24, depending on whether it is REAL32 or reial64 
respectively. 

If X is 'Not-a-Number' or infinity then the string will contain one of 
the following: 'inf\ -inf* or 'NaN', (excluding the quotes). 

2 If ip>0; Dp>0, fixed format is used, unless the value needs 
more than Ip significant digits before the decimal point, in which 
case, exponential format is used. If exponential does not fit either, 
then a signed string 'Ov' is produced. The length is always ip + 
Dp + 2 when lp>0 , Dp>0. 

If X is 'Not-a-Number" or infinity then the string will contain one of 
the following: "Inf , -Inf or 'NaN', (excluding the quotes) and 
padded out by spaces on the right to fill the field width. 

3 II ip=0, Dp>0, then exponential format is always used. The 
length of the result is Dp + 6 or Dp + 7, depending on whether 
X is a REAI.32 or REAL64, respectively. 

If lp=0; Dp=l, then a special result is produced consisting of 
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a sign, a blank, a digit and the exponent. The length is 7 or 8 
depending on whether x is a REAL32 or REAL64. Note: this 
result does not conform to the OCCam format for a real. 

If X is 'Not-a*Number' or infinity then the string wilf contain one of 
the following: 'Inf ', '-inf or 'NaN*, (excluding the quotes) and 
padded out by spaces on the right to fiJI the field width. 

All other combinations of ip and Dp are errors. 

If string is not long enough to hold the requested formatted real num- 
ber as a string then these routines act as invalid processes. 

REAL64TOSTRING 

PROC REAL64TOSTRING (INT len, []BYTE string, 

VAL RE:AL64 X, 
VAL INT Ip, Dp) 

As REAL32TOSTRING but fof 64-bit numbers. 

BOOLTOSTRING 

PROC BOOLTOSTRING {INT len, []BYTE String, 
VAL BOOL b> 

Converts a boolean value to a string. The procedure returns 'TRUE' in 
string if b is TRUE and 'FALSE' otherwise, len contains the number 
of characters In Ihe string returned. If string is not long enough to 
hold the representation then this routine acts as an invaHd process. 

STRINGTOINT 

PROC STRINGTOINT (BOOL Error, INT n, 
VAL [JBYTE string) 

Converts a string to a decimal integer. The procedure returns in n the 
value represented in string, error is set to TRUE if a non-numeric 
character is found in string or if string is empty. + or a - are 
allowed in the first character position, n will be the value of the portion of 
string up to any illegal characters, with the convention that the value of 
an empty string is 0. error is also set to TRUE if the value of string 
overflows the range of INT, in this case n wiil contain the low order bits 
of the binary represGntation of string, error is set to FALSE In all 
other cases. 

Similar procedures are provided for the types INT16, INT32 and INT64. 
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STRINGT0INT16 

PROC STRINGTOINTie (BOOL Error, IKT16 n, 

VAL []BYTE String) 

As STRINGTOINT but Converts to a 16-bit integer. 

STRINGTOINT32 

PROC STRINGTOINT32 (BOOL Error, INT32 n, 

VAL []BYTE String) 

As STRINGTOINT but converts to a 32-bit integer. 

STRINGTOINT64 

PROC STRINGTOINT64 (BOOL Error, INT64 n, 

VAL []BYTE string) 

As STRINGTOINT but converls to a 64-bit integer. 

STRINGTOHEX 

PROC STRINGTOHEX (BOOL Error, INT n, 
VAL []BYTE String) 

The procedure returns in n the value represented by the hexadecimal 
string. No '#' is allowed in the input and hex digits must be in upper 
case (A to F) rather than lower case (a to f). error is set to TRUE if a 
non-hexadecimal character is (ound in string, or if string is empty. 

n will be the vaiue of the portion of string up to any illegai charac- 
ter with the convention that the value of an empty string is 0. error 
is also set to true if the value represented by string overflows the 
range of int. In this case n will contain the iow order bits of the binary 
representation of string. In all other cases error is set to FALSE. 

Similar procedures are provided for the types hex16, hex32 and hex64. 

STRINGTOHEX16 

PROC STRINGT0HEX16 (BOOL Error, INT16 n, 

VAL []BYTE String) 

As STRINGTOHEX but converts to a 16-bit Integer. 
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STRINGTOHEX32 

PROC STRINGT0HEX32 (BOOL Error, INT32 n, 

VMi []BYTE String) 

As STRINGTOHEX but Converts to a 32-bit integer. 

STRINGTOHEX64 

PROC STRINGTOHEX64 (BOOL Error, INT64 n, 

VAL []BYTE string) 

As STRINGTOHEX but Converts to a 64-bit integer, 

STRINGTOREAL32 

PROC STRINGTOREAL32 (BOOL Error, REAL32 X, 

VAL [IBYTE String) 

Converts a string to a 32-bit real number. This procedure takes a string 
containing a decimal representation of a real number and converts it 
Into tl^e corresponding real value. If the value represented by string 
overflows the range of the type then an appropriately signed infinity is 
returned. Errors in the syntax of string are signalled by a 'Not-a- 
Number' being returned and error being set to TRUE. The string is 
scanned from the left as far as possible while the syntax is still valid. If 
there are any characters after the end of the iongest correct string then 
error is set to true, othenwise it is false. For example if string was 
"12.34£; + 2+1.0" then the value returned would be 12.34 x 10^ with 
error set to TRUE. 

STRINGTOREAL64 

PROC STR1NGTOREAL64 (BOOL Error, REAL64 X, 

VAL []BYTE String) 

As STRINGTOREAL32 but converts to a 64-bit number. 

STRINGTOBOOL 

PROC STRINGTOBOOL (BOOL Error, b, 

VAIi []BYTE string) 

Converts a string to a boolean value. The procedure returns true in b if 
the first four characters of string are 'true' and false if the first five 
characters are 'false'; b is undefined in other cases, true is returned 
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in error if string is not exactly 'TRUE' or 'FALSE'. 



1.8 Block CRC library 

Library: crc.lib 

The block CRC library provides two functions for generating CRC codes from byte 
strings. oldCRC is some agreed initialisation value e.g. zero or the polynomial 
generator. It may be, however, that the string that you want the CRC of, is not 
all available at once. In this case, although an initialisation is still required once, 
the value of the CRC from one segment of the string is used for OldCRC on the 
next segment, until all segments of the string are exhausted. 

For further information about CRC functions see 'iNMOS Technical note 26: 
Notes on graphics support and performance improvements on the IMS TSOO\ 



Result 


Function 


Parameter Specifiers 


INT 
INT 


CRCFROMMSB 
CRCFROMLSB 


VAL []BYTE InputString, 

VAL INT PolynomialGenerator, 

VAL INT OldCRC 

VAL []BYTE InputString 

VAL INT PolynoraialGenerator, 

VAL INT OldCRC 



1.8.1 Function definitions 

CRCFROMMSB 

INT FUNCTION CRCFROMMSB (VAL [ ] BYTE InputString, 

VAL INT PolynomialGenerator, 
VAL INT OldCRC) 

The string of bytes is polynomially divided by the generator, starting at 
the most significant bit of the most significant byte. 

CRCFROMLSB 



INT FUNCTION CRCFROMLSB (VAL [ ] BYTE InputString, 

VAL INT PolynomialGenerator, 
VAL INT OldCRC) 

The string of bytes is polynomially divided by the generator, starting at 
the least significant bit of the least significant byte. 
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1.9 Extraordinary link handling library 

Library: xlink.lib 

The extraofdfnary (ink handling library contains routines for handling communi- 
cation failures errors on a link. Four procedures are provided to allow failures on 
input and output channels to be handled by timeout or by signalling the failure 
on another channe]. A fifth procedure allows the channel to be reset. The use 
of these routines is described in part 1, section 10.5. 



Procedure 


Parameter Specifiers 


InputOrFail .t 
OutputOrFail -t 
InputOrFail , c 
OutputOrFail . c 
Reinitialise 


CHAN OF ANY C, []BYTE mess, 

TIMER t, VAL INT time, BOOL aborted 

CHAN OF ANY c, VAL []BYTE mess, 
TIMER t, VAL INT time, BOOL aborted 

CHAJH OF ANY C, []BYTE mess 
CHAN OF INT kill, BOOL aborted 

CHAN OF ANY c, VAL []BYTE mess, 
CHAN OF INT kill, BOOL aborted 

CHAN OF ANY c 



CAUTION: 

Use of the routines in xlink.lib during interactive debugging will Jead to 
undefined results. 



1,d.1 Procedure definUions 

The four procedures take as parameters a link channel c (on which the com- 
munication is to take place), a byte vector mess (which is the object of the 
communication), and the boolean variable aborted. The choice of a byte vec- 
tor for the message allows an object of any type to be passed along the channet 
providing it is retyped first. 

InputOrFail. t 

PROC InputOrFail. t (CHAN OF ANY c, [JBYTE mess, 

TIMER t, VAL INT time, 
BOOL aborted) 
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This procedure is used for communication where failure is detected by a 
timeout. It takes a timer parameter t, ar\d an absolute time time. The 
procedure treats the communication as having failed when the time as 
measured by the timer t is after the specified time time. 

OutputOrFail , t 

PROC OutputOrFail. t (CHAN OF ANY C, 

VAL []BYTE mess, 
TIMER t, VAL INT time, 
BOOL aborted) 

This procedure is used for communication where failure is detected by a 
timeout. It takes a timer parameter t, and an absolute time time. The 
procedure treats the communication as having failed when the time as 
measured by the timer t is after the specified time time. 

InputOrFail.c 

PROC InputOrFail.c (CHAN OF ANY c, []BYTE mess, 

CHAN OF INT kill, 
BOOL aborted) 

This procedure provides^ through an abort control channel, for commu- 
nication failure on a channel expecting an input. This is useful if failure 
cannot be detected by a simple timeout. Any integer on the channel 
kill will cause the channel c to be reset and this procedure to termi- 
nate. 

OutputOrFail . c 

PROC OutputOrFail. c (CHAN OF ANY c, 

VAL tlBYTE mess, 
CHAN OF INT kill, 
BOOL aborted} 

This procedure provides, through an abort control channel, for commu- 
nication failure on a channel attempting to output- This is useful if failure 
cannot be detected by a simple timeout. Any integer on the channel 
kill will cause the channel c to be reset and this procedure to termi- 
nate. 
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Reinitialise 

PROC Reinitialise (CHAN OF ANY c) 

This procedure may be used to remitiafise the link channel c after it is 
known that all activity on the Eink has ceased. 

Reinitialise must only be used to reinitialise a link channel alter 
communication has finished. If the procedure is applied to a link channel 
which is being used for communication the transputer's error flag will be 
set and subsequent behaviour is undefined- 
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1.10 Debugging support library 

Library: debug. lib 

The debugging support library provides four procedures. Two procedures are 
provided to stop a process, one on a specified condition. The \h\r6 procedure \s 
used to insert debugging nnessages and the fourth procedure is a timer process 
for analysing deadlocks. 



Procedure 


Parameter Specifiers 


DEBUG. ASSERT 
DEBUG. MESSAGE 
DEBUG. STOP 

DEBUG. TIMER 


VAL BOOL assertion 
VAL IIBYTE message 


CHAN OF INT Stop 



1.10.1 Procedure definitions 

DEBUG, ASSERT 

PROG DEBUG. ASSERT (VAL BOOL assertion) 

If a condition fails this procedure slops a process and notifies the debug- 
ger. 

If assertion evaluates FALSE, DEBUG. ASSERT Stops the process 
and sends process data to the debugger. If assertion evaluates true 
no action is taken. 

If the program is not being run within the breakpoint debugger and the 
assertion fails, then the procedure behaves like debug. stop. 
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DEBUG. MESSAGE 

PROC DEBUG. MESSAGE (VAL [JBYTE message) 

This procedure sends a message to the debugger which is displayed 
along with normal program output Note: that only the first 83 characters 
of the message are displayed. 

[f the program is not being run within the breakpoint debugger the pro- 
cedure has no effect. 

DEBUG. STOP 

PROC DEBUG. STOP {) 

This procedure slops the process and sends process data to the debug- 
ger. 

If the program is not being run within the breakpoint debugger then the 
procedure stops the process or processor, depending on the error mode 
that the processor is in. 

DEBUG. TIMER 

PROC DEBUG. TIMER (CHAN OF INT Stop) 

A timer process for use when anaiysing deadlocks in Occam programs. 
This procedure supports all current 16 and 32 bit transputers. The pro- 
cedure remains on the timer queue until receipt of any integer value on 
the channel stop, whereupon it will terminate. For an example of this 
process see pari 1, section 7.17.5. 
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1.11 Mixed languages support library 

Library: callclib 

This library provides four OCCam procedures for initialising static and heap areas 
and terminating them after use. They are provided to support the incorporation of 
code written in other languages such as C and FORTRAN into OCCam programs. 
Only code which is in the standard TCOFF format, used by this toolset may be 
incorporated using these procedures. 



Procedure 


Parameter Specifiers 


init . static 

in it .heap 

terminate . heap . use 
terminate . static .use 


[] INT static. area, INT 
recfuired.size, gsb 

VAL INT gsb, []INT 
heap . area 

VAL INT gsb 

VAL INT gsb 



1.11,1 Procedure definitions 

init , static 

PROC init. static (tl INT static. area, 

INT required. sizGr gsb) 

This function is used to set aside and initialise an area of memory for use 
as a static area. 

The static area is an integer array declared in the OCCain calling pro- 
gram. Two inleger values are obtained, as follows: 

required. size : The number of words of static space re- 
quired. 

gab : A pointer to the base of the array which will 

act as the global static base. 

Note: the number of words of static space required is equivalent to the 
size of the integer array. One element of the integer array is equivalent 
to one word of memory. 

If an error occurs when initialising the static area then the value 
MOSTPOS INT is returned instead of the required size. 
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init .heap 

PROC init. heap (INT gsb, VAL [ ] INT heap, area) 

This procedure is used to set aside an area of memory for use as a heap. 
The first argument is the gsb pointer returned by init . static, which 
is required because the memory allocation routines mal<e use o1 static 
data. 

As for the static area the heap area is declared as an integer array. 
This array must be large enough to accommodate all calls to C mem- 
ory allocation functions. The number of words of heap area required is 
equivalent to the size of the integer array. One element of the integer 
array is equivalent to one word of memory. 

If the heap is used by a function before init. heap has been called 
the memory allocation functions will fail with their normal error returns. 

terminate . heap . use 

PROC terminate. heap, use (VAL INT gsb) 

terminate* heap. use should be called when the heap is no longer 
required. It provides a clean way of terminating the use of the heap. 

Once the heap terminate procedure has been called the state of the heap 
is undefined and further calls to memory allocation functions will fail. 

terminate. heap. use must be called before terminating the static 
area because the heap requires static variables for its operation. 

terminate . static , use 

PROC terminate. static. use (VAL INT gsb) 

terminate * static . use Should be called when the static area is no 
longer required, usually when no further calls to other languages will be 
made. It provides a clean way of ending the use of the static area. 

Once the static terminate procedure has been called the state of the 
static area is undefined. 
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1.12 DOS specific hostio library 

Library: msdos.lib 

The i^SDOS host file server library allows programs to use some facilities specific 
to the IBM PC. A set of constants for the library are provided in the include file 
msdos . inc, which is listed in appendix C. 

Caution: Programs that use this DOS specific library wiil not be portable to 
versions of the toolset on other hosts. 



Procedure 


Parameter Specifiers 


dos . receive .block 


CHAN OF SP fs, ts, 




VAL rNT32 location, 




INT bytes, read, []BYTE block. 




BYTE result 


dos . send .block 


CHAN OF SP fs, ts. 




VAL INT32 location, 




VAL I] BYTE block, 




INT len, BYTE result 


dos . call . interrupt 


CHAN OF SP fs, ts. 




VAL INT 16 interrupt, 




VAL [dos . interrupt . regs . size] 




BYTE register .block. in, 




BYTE carry. flag, 




[dos , interrupt . regs . size] BYTE 




register . block . out , 




BYTE result 


dos. read. regs 


CHAN OF SP fs, ts, 




[dos .read. regs .size] BYTE 




registers. 




BYTE result 


dos. port .read 


CHAN OF SP fs, ts, 




VAL INT16 port .location, 




BYTE value, result 


dos , port , write 


CHAN OF SP fS, ts. 




VAL INT16 port, location, 




VAL BYTE value, BYTE result 
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1.12.1 Procedure definitions 

dos . receive . block 

PROC dos. receive. block (CHAN OF SP fs, ts, 

VAL rNT32 location, 
INT bytes, read, 
[]BYTE block, 
BYTE result) 

Reads a block of data, starting at location, from host memory, 
location is arranged as the segment in the top two bytes and the 
offset in the lower two bytes, both unsigned. 

The number bytes requested is size block; the number of bytes read 
is returned in bytes . read. The result returned can take any of the 
foilowing values: 

spr . ok The read operation was successful, 

spr. bad. packet .size Too many bytes were requested 

to be read: (Size block) > 

dos. max. recaiva. block, buffer, size. 



> Spr .Operation. failed 



The read failed, so bytes . read = 
0. If result takes a value 

> spr - operation , failed 

then this denotes a server returned 
faiiure. (See sections C,l and H.2.2). 



dos . send. block 

PROC dos. send, block (CHAN OF SP fs, ts, 

VAL INT32 location, 
VAL []BYTE block, 
INT len, BYTE result) 

Writes a block of data to host memory, starting at location. The 
location is arranged as the segment in the top two bytes and the 
offset in the lower two bytes, both unsigned. 

The number of bytes, requested to be written is SIZE block; the num- 
ber of bytes written is returned in len. The result returned can take any 
of the following values: 
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spr . ok The write operation was successful. 

spr. bad. packet .size Too many bytes were requested 

to be written: {SIZE block) > 
dos. max. send-block. buffer. size. 



> spr. operation, failed 



The write failed. If result takes a 

value 

> spr .operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 



dos . call . interrupt 

PROC dos . call . interrupt 
(CHAN OF SP fa, ta, 
VAL INT16 interrupt, 

VAi Idos. interrupt. regs. size] BYTE register .block. in, 
BYTE carry. flag, 

[dos , interrupt . rega . size] BYTE register . block . out , 
BYTE result) 

Invokes an interrupt call on the host PC, with the processor's registers ini- 
tialised to requested values. On return from the internjpt the values stored 
in the processor's registers are returned in register .block. out, 
along with the value of the carry flag on the PC, which is stored in 
carry, flag. 

The internjpt number is specified by interrupt. The registers are 
represented by a block of bytes called register. block. in. This 
block stores the values to be written to the registers. Each register value 
occupies 4 bytes of a block. On the IBM PC the 2 most significant bytes 
are ignored as this machine has only 2 byte registers (16 bit registers). 
The layout of registers in the block is as follows: 
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Register 


Start position in block 


End position in block 




(least significant b/te) 


(most significant byte) 


ax 





3 


bx 


4 


7 


ex 


8 


11 


dx 


12 


15 


di 


16 


19 


si 


20 


23 


cs 


24 


27 


ds 


28 


31 


es 


32 


35 


S5 


36 


39 



Note, however, that the cs and ss registers cannot be set. 
The result returned can take any of the following values: 

spr,ok The interrupt was successful. 

> spr. operation, failed The interrupt failed If result takes 

a value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.l and H.2.2). 



dos . read . regs 



PROC dos . read . regs 

(CHAN OF SP fs, ts, 

[dos . read.regs . size] BYTE registers, 

BYTE result) 

Reads the current values of some registers of the PC. The values of 
the registers are returned as a block of bytes, each register occupying 4 
bytes of the block: 



72 TDS 276 02 



March 1991 



1.12 DOS specific hostio library 



153 



Register 


Start position in block 


End position in block 




(least significant byte) 


(most significant byte) 


a:c 





3 


bx 


4 


7 


ex 


8 


11 


dx 


12 


15 



On the IBM PC the 2 most significant bytes are ignored as thts machine 
has only 2 byte registers (16 bit registers). 

The result returned can take any of the following values: 

spr.ok The read was successful. 

> spr. operation. failed The read failed. If result takes a 

value 

> spr . operation . failed 

then this denotes a server returned 
failure. (See sections C.1 and H. 2.2). 



dos . port . read 



PROC dos. port. read (CHAN OF SP fs, ts, 

VAL INT16 port .location, 
BYTE value, result) 

Reads the value at the port, specified by the port address, 
port. location. The port address being in the input/output space 
of the PC is an unsigned number between and 64K. 

No check is made to ensure that the value received from the port (if any) 
is valid. The value returned in value is that of the given address at the 
moment the port is read by the host file server. 

The result returned can take any of the following values: 

spr . ok The read was successfuL 

> spr. operation, failed The read failed. If result takes a 

value 

> spr. operation. failed 

then this denotes a server returned 
failure. (See sections C.I and H.2.2). 
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dos . port . write 

PROC dos. port. write (CHAN OF SP fs, ts, 

VAL INT16 port, location, 
VAL BYTE value, BYTE result) 

Writes the given value to the port specified by the port address, 
port .location. The port address being in the input/output space 
of the PC is an unsigned number between and 64K. 

No checl< is made to ensure that the value written to the port has been 
correctly read by the device connected to the port (if any). 

The result returned can take any of the following values: 

spr , ok The write was successful, 

> spr, operation. failed The write failed. If result takes a 

value 

> spr. operation. failed 

then this denotes a server returned 
lailure. (See sections C.I and H. 2.2). 
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software 



Alt names which may appear in OCCam source text and which are defined either 
by the language, the connpiler or the libraries are given below in alphabetical 
order. 

Toolset constants are not included; for listings of the constants files see ap- 
pendix C 

The names in this table are grouped into the following classes: 

1 Language keyword. Keyword defined in the language reference manual. 

2 Compiler keyword Keyword defined by the current compiler implemen- 
tation. 

3 OompHer predefine. A procedure or function which is predeclared by the 
compiler. On some processors these are implemented by a routine in 
a library with the name indicated, on others they are implemented as in 
line code. 

4 System library. Library routines for special transputer system operations. 
Consists of the libraries arc. lib and xlink.lib, 

5 Maths library. A function in the elementary function libraries. The library 
name depends on the version required (single or double length). 

6 Maths support. Supporting functions for routines in tbmathg . lib. 

7 I/O library. A procedure or function in the input/output and supporting 
libraries (hostio.lib, streamiclib, string. lib, 
process . lib, and convert , lib). The library name which must be 
used to access it is also shown. 

8 Debug library. Routines to help with interactive debugging. 

9 Compiler directive. A word in occam source code recognised by the 
compilation system for special action at compile time. The word is pre- 
ceded in Occam source either by the character '#' or by '#prrgma'. 

Any name which is not a language keyword may be redeclared as an identifier in 
an occam program. However, redefining a name of a compiler library procedure 
or function can have unexpected consequences and it is strongly recommended 
that all the names in these tables are reserved for the uses specified. 

72 TDS 276 02 March 1991 



158 



A Names defined by the software 



Name 


Class 


Library 


Notes 


T»BS 


compiler predefine 






ACOS 


maths library 


sngJmath 


also tbmaths 


AFTER 


language keyword 






AliOG 


matins library 


snglmath 


also tbmaths 


ALOGIO 


maths library 


snglmath 


also tbmaths 


ALT 


language keyword 






AKD 


language keyword 






ANY 


language keyword 






append. char 


io library 


string 




append . hex . int 6 4 


io library 


string 




append. hex, int 


io library 


string 




append » int 64 


io library 


string 




append , int 


Io library 


string 




append. real3 2 


io library 


string 




append, real 64 


io library 


string 




append. text 


io library 


string 




ARGUMENT . REDUCE 


compiler predefine 






ASHIFTLEFT 


compiler predefine 






ASHIFTRIGHT 


compiler predefine 






ASIN 


maths library 


snglmath 


also tbmaths 


ASM 


compiler keyword 






ASSERT 


compiler predefine 






AT 


language keyword 






ATAN 


maths library 


snglmath 


also tbmaths 


ATAN2 


maths library 


snglmath 


also tbmaths 


BITAND 


language keyword 






BITCOUNT 


compiler predefine 






BITNOT 


language keyword 






BITOR 


language keyword 






BITREVNBITS 


compiler predefine 






BITREVWORD 


compiler predefine 






BCX>L 


language keyword 






BOOLTOSTRING 


io library 


convert 




BYTE 


language keyw6rd 






CASE 


language keyword 






CAUSRF.RROR 


compiler predefine 






CHAN 


language keyword 






char.pos 


io library 


string 




CLIP 2D 


compiler predefine 






COMMENT 


compiler directive 






compare , strings 


io library 


string 
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Name 


Class 


Library 


Notes 






COPYSIGK 


compiler predefine 










COS 


maths library 


sngimath 


also tbmaths 






coss 


maths library 


sngimath 


also tbmaths 






CRCBYTE 


compiler predefine 










CRCFROMLSB 


system library 


crc 








CRCFROMMSB 


system library 


crc 








CRCWORD 


compiler predefine 










DABS 


compiler predefine 










DACOS 


maths library 


dblmalh 


also tbmaths 






DALOG 


maths library 


dblmath 


also tbmaths 






DALOGIO 


maths library 


dblmath 


also tbmaths 






DARGUMENT . REDtTCE 


compiler predefine 










DAS IN 


maths library 


dblmath 


also tbmaths 






DATAN 


maths library 


dblmath 


also tbmaths 






DATAN2 


maths library 


dblmath 


also tbmaths 






DCOPYSIGN 


compiler predefine 










DCOS 


maths library 


dblmath 


also tbmaths 






DCOSH 


maths library 


dblmath 


also tbmaths 






DDIVBY2 


compiler predefine 










DEBUG. ASSERT 


debug library 


debug 








DEBUG. MESSAGE 


debug library 


debug 








DEBUG, STOP 


debug library 


debug 








DEBUG. TIMER 


debug library 


debug 








delete . string 


io library 


string 








DEXP 


maths library 


dblmath 


also tbmaths 






DFLOATING . UNPACK 


compiler predefine 










DFPINT 


compiler predefine 










DIEEECOMPARE 


compiler predefine 










DISNAN 


compiler predefine 










DIVBY2 


compiler predefine 










DLOGB 


compiler predefine 










DMINUSX 


compiler predefine 










DMDLBY2 


compiler predefine 










DNEXTAFTER 


compiler predefine 










DNOTFIKITE 


compiler predefine 










DORDERED 


compiler predefine 










DPOWER 


maths library 


dblmath 


also tbmaths 






DRAN 


maths library 


dblmath 


also tbmaths 






DRAW2D 


compiler predefine 










DSCAIiEB 


compiler predefine 
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Name 


Class 


Library 


Notes 






DSIK 


maths library 


dblmath 


also tbmaths 






DSINH 


maths library 


dbfmath 


also tb maths 






DSQRT 


compiler predefine 










DTAN 


maths library 


dblmath 


also tbmaths 






DTANH 


maths library 


dblmath 


also tbmaths 






ELSE 


language keyword 










eqstr 


io libraiy 


string 








EXP 


maths library 


snglmath 


also tbmaths 






EXTKRHAL 


compiler directive 










FAliSE 


language keyword 










FLOATING . UNPACK 


compiler predefine 










FOR 


language keyword 










FPINT 


compiler predefine 










FRACMUL 


compiler predefine 










FROM 


language keyword 










FUNCTION 


language keyword 










GUY 


compiler keyword 










HEX16T0STRING 


io library 


convert 








HEX32T0STRING 


io library 


convert 








HEX64TOSTRING 


io library 


convert 








HEXTOSTRING 


Io library 


convert 








IEEE320P 


compiler predefine 










IEEE32REM 


compiler predefine 










IEEE 6 4 OP 


compiler predefine 










IEEE 6 4 REM 


compiler predefine 










lEEECOMPARE 


compiler predefine 










IF 


language keyword 










IMPORT 


compiler directive 










IN 


language keyword 










INCLUDE 


compiler directive 










INLINE 


compiler keyword 










InputOrFail . c 


system library 


xlink 








InputOrFail .t 


system library 


xJink 








insert. string 


io library 


string 








INT 


[anguage keyword 










INT16 


language keyword 










INT16T0STRING 


io library 


convert 








INT32 


language keyword 










INT32T0STRING 


io library 


convert 








INT64 


language keyword 
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Name 


Class 


Library 


Notes 


INT64TOSTR1NG 


io Eibrary 


convert 




INTTOSTRING 


io library 


convert 




IS 


language keyword 






is . digit 


io library 


string 




is. hex, digit 


io library 


string 




is. id. char 


io library 


string 




is. in. range 


io library 


stiing 




is . lower 


io library 


string 




is. upper 


Io library 


string 




ISNAN 


compiler predefine 






KERNEL. RUN 


compiler predefine 






ks . Iceystream . sink 


io library 


streamio 




ks . keystream . to . scrstream 


io library 


streamio 




ks, read -Char 


io library 


streamio 




ks.read.int 


io library 


streamio 




ks.read.int64 


io library 


streamio 




ks. read, line 


io library 


streamio 




ks,r€ad.real32 


io library 


streamio 




ks . read. real64 


io library 


streamio 
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Name 


Class 


Libr 


Notes 


LINKAGE 


compiler directive 






LOJVD . BYTE . VECTOR 


compiler predefine 






LOAD . INPUT . CHANNEL 


compiler predefine 






LOAD , INPUT . CHANNEL , VECTOR 


compiler predefine 






LOAD . OUTPUT . CHANNEL 


compiler predefine 






LOAD . OUTPUT , CHANNEL . VECTOR 


compiler predefine 






LOGB 


compiler predefine 






LONGADD 


compiler predefine 






LONGDIFF 


compiler predefine 






LONGDIV 


compiler predefine 






LONGPROD 


compiler predefine 






LONGSUB 


compiler predefine 






LONGSUM 


compiler predefine 






MINUS 


language keyword 






MINUSX 


compiler predefine 






MOSTNEG 


language keyword 






MOSTPOS 


language keyword 






M0VE2D 


compiler predefine 






MULBy2 


compiler predefine 






next . int . from . line 


io library 


string 




next . word . from . 1 ine 


io library 


string 




NEXTAFTER 


compiler predefine 






NORMALISE 


compiler predefine 






NOT 


language keyword 






NOTFINITE 


compiler predefine 






OF 


language keyword 






OPTION 


compiler directive 






OR 


language keyword 






ORDERED 


compiler predefine 






OutputOrFail.c 


system library 


xlink 




OutputOrFail.t 


system library 


xlink 




PAR 


language keyword 






PLACE 


language keyword 






PLACED 


ianguage keyword 






PLUS 


ianguage keyword 






PORT 


ianguage keyword 
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Name 


Class 


Library 


Notes 


POWER 


maths library 


snglmath 


also tbmaths 


PRAGZ^ 


compiler directive 






PRI 


language keyword 






PROC 


language keyword 






PROCESSOR 


language keyword 






PROTOCOL 


language keyword 






RAN 


maths library 


snglmath 


also tbmaths 


REAL32 


language keyword 






REAL32EQ 


compiler predefine 






REfl 1.3207 


compiler predefine 






REAL320P 


compiler predefine 






REAL32REM 


compiler predefine 






REAL32TOSTRING 


io library 


convert 




RRAL64 


language keyword 






REAL64EQ 


compiler predefine 






REAL64GT 


compiler predefine 






REAL640P 


compiler predefine 






REAL64REM 


compiler predefine 






KEAL64TOSTRING 


to library 


convert 




Reinitialise 


system library 


xlink 




REM 


language keyword 






RESCHEDULE 


compiler predefine 






RESULT 


language keyword 






RETYPES 


language keyword 






ROTATELEFT 


compiler predefine 






ROTATERIGHT 


compiler predefine 






ROUND 


language keyword 






ROUNDSN 


compiler predefine 




not T2s 


SC 


compiler directive 






SCALES 


compiler predefine 






search. match 


io library 


string 




search. no. match 


io library 


String 




SEQ 


language keyword 






SHIFTLEFT 


compiler predefine 






SHIFTRIGHT 


compiler predefine 






SIN 


maths library 


snglmath 


also tbmaths 


SINH 


maths library 


snglmath 


also tbmaths 
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Name 


Class 


Library 


SIZE 


language keyword 




SKIP 


language keyword 




SO. ask 


io library 


hostio 


so. buffer 


io library 


hostio 


so, close 


io library 


hostio 


so . commandline 


io library 


hostio 


so . core 


io library 


hostio 


so . date . to . ascii 


io library 


hostio 


so.eof 


io library 


hostio 


so. exit 


io library 


hostio 


so . f error 


io library 


hostio 


so, flush 


io library 


hostio 


so . f write . char 


io library 


hostio 


so , f write , hex . int 


io library 


hostio 


so , fwrite , hex . int32 


io library 


hostio 


so . fwrite . hex . int 64 


io library 


hostio 


so. fwrite. int 


io library 


hostio 


so. fwrite. int32 


io library 


hostio 


so . fwrite , int 64 


io library 


hostio 


so.fwrite.nl 


io library 


hostio 


so . fwrite . real32 


io library 


hostio 


so . fwrite . real64 


io library 


hostio 


so . fwrite . string 


io library 


hostio 


so. fwrite.string.nl 


io library 


hostio 


so . getenv 


io library 


hostio 


so . get key 


io library 


hostio 


so, gets 


io library 


hostio 


so * keystream . from , file 


io library 


stream io 


so . keyst ream . from , kbd 


io library 


streamio 


so , keystream . from . stdin 


io library 


stream Io 


so . multiplexor 


io library 


hostio 


so , open 


io library 


hostio 


so. open. temp 


io library 


hostio 


so . overlapped . buffer 


io library 


hostio 


so , overlapped . multiplexor 


io library 


hostio 


so . overlapped . pri . multiplexor 


io library 


hostio 
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Name 


Class 


Library 


Notes 


so , parse . command . line 


io library 


hostio 




so.pollkey 


io library 


hostio 




so . popen . read 


io library 


hostio 




so , pr i . mult iplexor 


io library 


hostio 




so. puts 


io library 


hostio 




so. read 


io library 


hostio 




so - read . echo . any . int 


Io library 


hostio 




so , read . echo . hex . int 


io library 


hostio 




so . read . echo . hex . int32 


io library 


hostio 




so . read . echo . hex . int 64 


io library 


hostio 




so > read . echo . int 


io library 


hostio 




so . read . echo . int 3 2 


io library 


hostio 




so . read . echo . int 64 


io library 


hostio 




so . read . echo , line 


io library 


hostio 




so . read . echo . real32 


io library 


hostio 




so . read . echo . real64 


io library 


hostio 




so. read. line 


10 library 


hostio 




so , remove 


io library 


hostio 




so . rename 


io library 


hostio 




so.scrstream.to.ANSI 


io library 


stream io 




so . scrstream . to . file 


io.library 


streamio 




so , scrstream . to . stdout 


io library 


stream io 




so , scrstream. to , TVI 920 


Io library 


stream io 




so. seek 


io library 


hostio 




so . system 


io library 


hostio 




so. tell 


io library 


hostio 




so .test . exists 


io library 


hostio 




so, time 


io library 


hostio 




so. time. to. ascii 


io library 


hostio 




so , time . to . date 


io library 


hostio 




so. today. ascii 


io library 


hostio 




so . today . date 


io library 


hostio 




so, vers ion 


io library 


hostio 




so. write 


io library 


hostio 




so , write . char 


io library 


hostio 




so . write . hex . int 


io library 


hostio 




so .write .hex . int32 


io library 


hostio 




so -write. hex. int 6 4 


io library 


hostio 




so. write. int 


io library 


hostio 





72 IDS 276 02 



March 1991 



166 



A Names defined by the software 



Name 


Class 


Library 


so .write . int32 


io library 


hostio 


so .write . int64 


Jo library 


lioslio 


so.write.nl 


io library 


hostio 


so . write . real32 


io library 


hostio 


so. write. real64 


io library 


hostio 


so . write . string 


io library 


hostio 


so . write , string . nl 


io library 


hostio 


sp. buffer 


io library 


hostio 


sp. close 


io library 


hostio 


sp . commandline 


io library 


hostio 


sp . core 


io library 


hostio 


sp .eof 


io library 


hostio 


sp.exit 


io library 


hostio 


sp . f error 


io library 


hostio 


sp. flush 


io library 


hostio 


sp . getenv 


io library 


hostio 


sp . getkey 


io library 


hostio 


sp.gets 


io library 


hostio 


sp . multiplexor 


io library 


hostio 


sp , open 


io library 


hostio 


sp . overlapped . buffer 


io library 


hostio 


sp . overlapped .multiplexor 


io library 


hostio 


sp . overlapped. pri .multiplexor 


io library 


hostio 


sp.pollkey 


io library 


hostio 


sp .pri .multiplexor 


io library 


hostio 


sp.puts 


Io library 


hostio 


sp . read 


io library 


hostio 


sp . receive . packet 


io library 


hostio 


sp - remove 


io library 


hostio 


sp . rename 


io library 


hostio 


sp.seek 


io library 


hostio 


sp . send . packet 


io library 


hostio 


sp, system 


io library 


hostio 


sp.tell 


io library 


hostio 


sp.time 


io library 


hostio 


sp, vers ion 


io library 


hostio 


sp. write 


io library 


hostio 


SQRT 


compiler predefine 




ss .beep 


io library 


streamio 
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Name 


Class 


Library 


Notes 


ss , clear -eol 


io library 


streamio 




5S. clear. eos 


io library 


streamio 




ss. del. line 


io library 


streamio 




ss. delete. chl 


io library 


streamio 




33.delete.chr 


io library 


streamio 




ss.down 


Io library 


streamio 




ss .goto.xy 


io library 


streamio 




ss . ins .line 


io (ibrary 


streamio 




ss . insert . char 


io library 


streamio 




ss.left 


io library 


streamio 




ss . right 


io library 


streamio 




ss . scrstream . copy 


io library 


streamio 




ss* scrstream. fan. out 


io library 


streamio 




ss. scrstream. from. array 


io library 


streamio 




ss . scrstream .multiplexor 


Io library 


streamio 




ss . scrstream . sink 


io library 


streamio 




ss .scrstream. to. array 


io library 


streamio 




ss .up 


io library 


streamio 




ss. write. char 


io library 


streamio 




s s . write . endstream 


io library 


streamio 




ss . write . hex . int 


Io library 


streamio 




ss .write. hex. int 64 


io library 


streamio 




ss, write. int 


io library 


streamio 




S3. write. int 64 


io library 


streamio 




ss .write.nl 


io library 


streamio 




ss . write . real32 


Io library 


streamio 




ss .write. real64 


Io library 


streamio 




ss .write. string 


io library 


streamio 




ss .write . text , line 


io library 


streamio 




STOP 


language keyword 






str. shift 


io library 


string 




string. pos 


io library 


string 




STRINGTOBOOL 


io library 


convert 
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Name 


Class 


Library 


Notes 


STRINGTOHRX 


io fibrary 


convert 




STRINGT0HEX16 


io library 


convert 




STRINGTOHEX32 


io library 


convert 




STRINGTOHKX64 


io library 


convert 




STRINGTOINT16 


io library 


convert 




STRINGTOINT32 


io library 


convert 




STRIMGTOINT64 


io library 


convert 




STRINGTOINT 


io library 


convert 




STRINGT0REAL32 


io library 


convert 




STRINGTOREAL64 


io library 


convert 




TAN 


maths library 


snglmath 


also tbmaths 


TANH 


maths library 


snglmath 


also tbmaths 


TIMER 


language keyword 






TIMES 


language keyword 






to. lower .case 


io library 


string 




to. upper .case 


io library 


string 




TRANSLATE 


compiler directive 






TRDE 


language keyword 






TRDNC 


language keyword 






UNPACKSH 


compiler predefine 




not T2s 


USE 


compiler directive 






VAL 


language keyword 






VALOF 


language keyword 






VEC SPACE 


compiler keyword 






WHILE 


language keyword 






WORKSPACE 


compiler keyword 
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This appendix contains the list of transputer instructions supported by the toolset 
restricted code insertion facility, and gives the mnemonic for each instruction. All 
the instructions listed can be inserted into Occam programs using the asm 
construct. The appendix ends with a summary of the differences between the 
ASM and GUY constructs and describes the restrictions placed on the use of GUY 
code. 

The instructions described are available when the compiler is targetted to an 
MS T212. M212, T222. T225. T400, T414. T425. T800. T801. or T805 unless 
otherwise indicated. Instructions that are only supported when the compiler is 
targetted to certain processor types, are given in separate sections. The reader 
is referred to the 'Transputer instruction set: a compiler writer's guide' for further 
details of the instruction set. Details of the instructions listed in section B.8 are 
given in The transputer databook'. 



B.1 Pseudo-instructions 

Pseudo-instruclions are instructions to the assembler, rather than fnje transputer 
instnjclions. 

Expressions used in load or store pseudo instructions must be word sized or 
smaller. To load a floating point value, use a LD to load its address, then a 
FPLDNLSN or FPLDNLDB as required. 

The following pseudo-instojctions are implemented: 

BYTE This instruction takes as an argument a list of constant val- 

ues in the range to 255, or a list of (constant) byte arrays 
or strings. The assembler copies the literal bytes into the 
instajction stream. 

LD Loads a value into the Areg. 

LDAB Loads values into the Areg and Breg, The left hand expres- 

sion is placed in Areg. 

LDABC Loads values into Areg, Breg and Creg. The leftmost ex- 

pression is placed in Areg. 

LDLABELDIFF Loads the difference between the addresses of two labels into 
Areg. 
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ST Stores the value from the Areg. 

STAB Stores values into the Areg and Breg. The leftmost element 

receives Areg. 

STABC Stores values into the Areg, Breg, and Creg. The leftmost 

element receives Areg. 

WORD Generates constants of the target-machine word length. This 

instruction takes as an argument a list of INTs or INT (con- 
stant) arrays. 

The LD, LDAB, ST, and STAB instructions may use other registers and/or tem- 
poraries. LDABC and STABC may use temporaries. 



B.2 Prefixing instructions 

The transputer instruction set Is built up from 16 direct instnjctions^ each with 
a 4'bit argument field. The direct instructions include prefix inslnjctlons which 
augment the 4-bit field in a direct instruction which follows them by their own 
4-bit argument field, effectively allowing the argument to be extended to 32 bits, 
Normaliy, the assembler wiil compute the prefix instructions required for operand 
values greater than 4 bits automatically. 

PFix prefix 

NFIX negative prefix 
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B.3 Direct instructions 

The direct instructions form the core of the transputer instruction set. Each 
direct instruction has a single operand, normally an integer constant, which will 
be encoded in the Instruction itself and, if it is larger than will fit into the 4- 
bit argument field of the direct instnjction, into a series of PFix and NFix 
instructions as well. 

The transputer architecture is based around a three-register evaluation stack 
and a single base register Wreg. The load and store 'iocai' instructions access a 
word in memory at a displacement from Wreg given by the operand value used. 
The displacement Is scaled by the word size. The load and store 'non-local' 
instructions use the top evaluation stack register (Areg) as the base instead of 
Wreg, allowing computed base addresses \o be used. 

The operand of the J, CJ and CALL instructions is interpreted as a byte dis- 
placement from the instruction pointer (program counter) register Iptr. LDPI is 
similar but takes its operand from Areg. 

ADC Add constant operand value to Areg 

Ajw Adjust workspace pointer Wreg by constant operand value (scaled by 
word length) 

CALL Call 

c J Conditional jump i.e. 'jump if zero otherwise pop Areg'. As with jump, 

a label identifier may be used as argument to this instruction. 

EQC Test if Areg equals constant; Areg gets 1/0 result 

J Jump: the argument may be an identifier indicating a label for the 

jump to go to; the assembler will compute the displacement required. 

LDC Load constant 

LDL Load local word 

LDLP Load pointer to local word 

LDKL Load non-local word 

IDNLP Load pointer to non-local word 

OPR 'operate': the argument to this instnjction is a code indicating a zero- 

operand indirect instruction to be executed. Most of the transputer 
instnjction set is made up of these indirect instructions. Normally you 
would use the mnemonic for the specific indirect instruction which you 
require: the assembler will encode this as an opr instruction on your 
behalf. However, it is possible to use opr explicitly, for example to 
synthesise the instruction sequence for a new indirect instruction not 
supported by the T414 and T800 transputers. 

STL Store local word 

STNL Store non-local word 
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BA Operations 

The instructions in this section are all indirect instructions built out of the OPR 
instruction. None of these instructions take an argument; instead, they work 
solely with the transputer evaluation stack. 

The arithmetic instructions take their operands from the top of the evaluation 
stack (Areg, Breg) and push the result value back on the stack in Areg. 



B.4,1 Short indirect instructions 



ADD 

BSUB 

DIFF 

GT 

I£ 

PROD 

REV 

StJB 

WSUB 



Add 

Byte subscript (Areg = Areg + Breg) 

Difference 

Greater than (result Inje' or 'false', placed in Areg) 

Load byte 

Product 

Reverse top two stack elements 

Subtract 

Word subscript (Areg = Areg + 4*Breg) (32-bJt) 

Word subscript (Areg - Areg + 2*Breg) (16-bit) 



B.4,2 Long indirect instructions 



AND 


Bit-wise and 


BCNT 


Byte count 


CCNTl 


Check count from 1 


CSNGL 


Check single 


CSUBO 


Check subscript from 


CWORD 


Check word 


DIV 


Divide 


FMUL 


Fraclionat multiply (32-bit processors only) 


LADD 


Long add 


LDIFF 


Long difference 


LDIV 


Long divide 
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LDP I 


Load pointer to instruction (Areg is byte displacement from 




Iptr) 


LDPRI 


Load current priority 


LDTIMER 


Load timer 


LMUL 


Long multiply 


LSHL 


Long shift left 


LSHR 


Long shift right 


LSUB 


Long subtract 


LSOM 


Long sum 


MIMT 


Minimum integer 


MOVE 


Wove block of memory (src: Creg dest: Breg len: Areg) 


MUL 


Multiply 


NORM 


Normalise 


NOT 


Bit-wise not 


OR 


Bit-wise inclusive or 


REM 


Remainder 


SB 


Store byte 


SETKKR 


Set error 


SHL 


Shift left 


SHR 


Shift right 


STTIMER 


Store timer 


SUM 


Sum 


TESTERR 


Test error false and clear 


TESTHALTERR 


Test halt-on-error 


TESTPRAKAL 


Test processor analysing 


WCNT 


Word count 


XDBLE 


Extend to double 


XOR 


Bit-wise exciusive or 


XWORD 


Extend to word 
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B.5 Additional instructions for the T400, T414, T425 and TB 

The indirect instructions in this section may only be executed on a T400, T414 
or T425 processor. 

CFLERR Check single-length floating-point infinity or not-a-number 

LDINF Load single-length infinity 

POSTKORMSN Post-normalise correction of single-length floating-point 

number 
ROtJNDSN Round Single-length fioating-point number 

DNPACKSN Unpack single-length floating-point number 



B.6 Additional instructions for the IMS T800, T801 and T805 

The instructions in this section may only be executed on T800, TB01 and T805 
processors. 

B.6.1 Floating-point instructions 

The indirect instructions in this section provide access to the T8 series built-in 
floating-point processor. Note that the instructions beginning with *fpu. ..' are 
doubEy indirect: they are accessed by loading an entry code constant with a ldc 
instnjction, then executing an FPENTRY instnjction, which is itsetf indirect. As 
with ordinary indirect instructions, this indirection is handled transparently by the 
assembler, although the fpentry instruction is also available. 

The floating point load and store instructions use the integer Areg as a pointer 
to the operand location. 



FPADD 


Floating-point add 


FPB32TOR64 


Convert 32-bit unsigned integer to 64'bit real 


FPCHKERR 


Check floating error 


FPDIV 


Floating-point divide 


FPDUP 


Floating duplicate 


FPENTRY 


Floating point unit entry:. used to synthesise the 'FPU. 




Instnjctions. 


FPEQ 


Floating point equality 


FPGT 


Floating point greater than 
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FPI32TOR32 Convert 32-bit integer to 32-bit real 

FPI32T0R64 Convert 32-bit integer to 64-blt real 

FPINT Round to floating integer 

FPLDNLADDDB Floating load non-local and add double 

FPLDNLADDSN Floating load non-local and add single 

FPLDNLDB Floating load non-local double 

FPLDNLDBI Floating load non-local indexed double 

FPLDNLMULDB Fioating load non-Jocat and multiply double 

FPLDNnLMOLSN Fioating load non-local and multiply single 

FPLDNLSN Floating load non-local single 

FPLDNLSNI Floating load non-local indexed single 

FPLDZERODB Fload zero double 

FPLDZEROSN Load zero single 

FPMUL Floating-point multiply 

FPNAN Floating point not-a-number 

FPNOTFINITE Floating point finite 

FPORDERED Floating point orderability 

FPREMFIRST Floating-point remainder first step 

FPREMSTEP Floating-point remainder iteration step 

FPREV Floating reverse 

FPRT0I32 Convert floating to 32-bit integer 

FPSTNLDB Floating store non-local double 

FPSTNLI32 Store non local int32 

FPSTNLSN Floating store non-local single 

FPSUB Floating-point subtract 

FPTESTEKR Test floating error false and dear 

FPDABS Floating-point absolute 

FPUCHKI32 Check in range of 32-bit integer 

FPUCHKI64 Check in range of 64-bit integer 

FPUCLRERR Clear floating error 

FPUDIVBy2 Divide by 2.0 

FPUEXPDEC32 Divide by 2^^ 

FPUEXPINC32 Multiply by 2^^ 

FPUMULBY2 Multiply by 2,0 

FPONORODND Convert 64-blt real to 32-bit real without rounding 
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FPDR32TOR64 

FPUR64TOR32 

FPURM 

FPDRN 

FPDRP 

FPURZ 

FPOSETERR 

FPOSQRTFIRST 

FPUSQRTLAST 

FPUSQRTSTEP 



Convert single to double 

Convert double to single 

Set rounding mode to round minus 

Set rounding mode to round nearest 

Set rounding mode to round positive 

Set rounding mode to round zero 

Set floating error 

Floating-point square root first step 

Floating-point square root end 

Floating-point square root step 



BJ Additional instructions for the IMS T225, T400, T425, 
T800, T801 and T805 

The indirect instructions in this section supplement the T414's integer instruction 
set. 

BITCNT Count the number of bits set In a word 

BITREVNBITS Reverse bottom n bits in a word 

BITREVWORD Reverse bits in a word 

CRCBYTE Calculate CRC on byte 

CRCWCRD Calculate Cyclic Redundancy Check (CRC) on worti 

DUP Duplicate top of stack 

WSUBDB Form double-word subscript 

The following 2-dimensional block move instructions apply to the IMS T400, 
T425, T800, T801 and T805 only: 

M0VE2DALL 2-dimensional block copy 

M0VE2DINIT Initialise data for 2-dimensional block move 

MOVE2DNON2ERO 2-dimensional block copy non-zero bytes 

MOVE2DZERO 2'dimensional block copy zero bytes 
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B.8 Additional instructions for the EMS T225, T400, T425, 
T801 and T805 

The indirect instructions listed in tinis section provide debugging and general 
support functions- 

CLRJOBREAK Clear jump break enable flag 

SETJOBREAK Set jump break enable flag 

TEST JOBREAK Test If jump break Hag is set 

TiMERDiSABLEH Disable high priority timer Interrupt 

TIMERDISABLEL Disable low priority timer interrupt 

TIMERENABLEH Enable high priority timer interrupt 

TlMEREl^ABLEL Enable low priority timer Interrupt 

LDMEMSTARTVAii Load value of MemStart address 

POP Pop processor stack 

LDDEVID Load device identity 

B.9 Differences between ASM and GUY 

The ASM a>nstruct has very different semantics to guy code. This means that 
simply changing the word 'GUY' to 'asm' within your code, will usually break the 
code. 

The following list summarises the differences between GUY and asm code and 
outlines the restrictions now placed on using guy constructs. 

• A primary instruction in ASM code aiways generates that primary instnjc- 
tlon in the object file; this was not always the case with the GUY constnjct. 

• There are differences In the instructions used to perform load and store 
operations depending on whether a GUY or ASM construct is used. 

- The statements LDL x and LDNL x In GUY code both generate 
code which behaves as ld x in asm code. They may generate 
one or more transputer instructions. 

- The statements ldlp x and ldnlp x in guy code both gen- 
erate code which behaves as LD ADDRESSOF x in ASM code. 
They may generate one or more transputer Instructions. 

- The statements STL x and STNL x in GUY code both generate 
code which behaves as ST x in asm code. They may generate 
one or more transputer instructions. 
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- If a GDY construct is changed to an ASM construct then changes 
of loads and stores using any of these primary operations to the 
corresponding pseudo-operations should aiways be performed. 

- Use of these primary operations directly in asm code is not usu- 
ally necessary or desirable. In ASM code each primary load or 
store statement will generate a single, possibly prefixed, trans- 
puter instruction^ whose operand is the oflset within workspace of 
the variable named. Whether the location at this offset is a value 
or a pointer depends on whether the name is of a local variable 
(or value parameter) or not. 

• References to labels In GUY code are preceded by a full slop whereas 
in ASM they are preceded by a colon. 



Symbolic access to channels is not permitted in GUY code although It 
was in previous releases of the toolset {i.e. the IMS D705/D605/D505 
products). This is due to the fact that the internal representation of chan- 
nels has changed; the base data type of a channel is now ^pointer to 
channel'. (See part 1 section 10-1.3). 

In ASM code, ld c will return the address of the channel, whereas LD 
ADDRESSOF c Will return the address of a pointer to the channel. 
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This appendix lists the constants provided with the Occam libraries. The con- 
stants are supplied in text files and are given the extension . inc (for 'include'). 
These files should be placed on the path specified by the isearch environment 
variable. 

There are six separate files containing toolset constants, as follows: 



File 


Contents 


host io. inc 
streamio . inc 
mathvals. inc 
linkaddr.inc 
ticks. inc 
msdos, inc 


Hostio values and protocols 
Streamio values and protocols 
Mathematical constants 
Transputer link addresses 
Rates of the two transputer clocks 
DOS specific constants 



To use any of these files in a program, incorporate the file into the source using 
the #IHCLUDE directive as follows: 

# INCLUDE "hostio . inc" 

Constants must be declared before they are used in a program or library. 
C.1 Hostio constants 



-- hostio. inc 

— Copyright 1989 INMOS Limited 

— updated for iserver vl.42 apart from buffer size 5--June-90 SRH 

— SP protocol 

PROTOCOL SP IS INT16: : [IBYTE : 

— Command tags 

— values up to 127 are reserved for use by IKMOS 

File comaaAd tags 



VAL sp. open. tag 
VAX sp. close. tag 
VAL sp. read. tag 
VAX sp . write . t ag 
VAX sp. gets. tag 
VAX sp. puts. tag 
VAX sp. flush. tag 
VAX sp . seek . tag 
VAX sp. tell. tag 
VAL sp.eof.tag 
VAL sp. f error. tag 
VAL sp . remove , tag 
VAL sp. rename. tag 



IS 10 (BYTE) 
is 11 (BYTE) 
IS 12 (BYTE) 
IS 13 (BYTE) 
15 14 (BYTE) 
IS 15 (BYTE) 
IS 16 (BYTE) 
IS 17 (BYTE) 
IS IS (BYTE) 
IS 19 (BYTE) 
IS 20 (BYTE) 
IS 21 (BYTE) 
IS 22 (BYTE) 
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VAX sp,getblock.tag IS 23 (BYrE) 
VAL sp,putblook.tag IS 24 (BYTE ) 
VAL ap.i3atty.tag IS 25CBYrE) 

Host command tags 
VAL sp.getkey.tag IS 
VAL sp . pollkey . tag IS 
VAL sp.getenv.tag IS 
VAL sp. time. tag IS 
VAL sp. system. tag IS 
VAL sp. exit. tag IS 



30 (BYTE) 
31 (BYTE) 

32 (BYTE) 

33 (BYTE) 
34 (BYTE) 
35 (BYTE) 



— Server coaunaAd tags 

VAL sp. commandline .tag IS 40 (BYTE) 

VAL sp, core. tag IS 41(BYTE) 

VAL Sp. version. tag IS 42 (BYTE) 

OS specific conmand tags 

Thesd OS specific tags will be followed by anotlier tag 

indicating which OS specific function is required 

VAL sp. DOS. tag IS 50 (BYTE) 

VAL sp. HELIOS, tag IS 51 (BYTE) 

VAL sp. VMS, tag IS 52 (BYTE) 

VAL sp. SUNOS. tag IS 53 (BYTE) 



— Packet and buffer Sized 

VAL sp. max. packet .size IS 512 : 

- — bytes transferred, includes length & data 

VAL sp.min. packet .size IS 8 : 

— bytes transferred, includes length & data 

VAL sp.max.packet. data, size IS sp. max. packet .size - 2 : 

— INT16 length 

VAL sp.min. packet. data. Size IS sp. min. packet . sire - 2 : 

— 1HT16 length 

Individual command maxima 
VAL sp.max.openname. siste IS sp. max. packet. data. size - 5 

— 5 bytes extra 

VAL sp. max. readbuffer. size IS ap. max. packet. data. size - 3 

— 3 bytes extra 

— ditto for gets 

VAL sp.max.writebuffer.si^e IS Bp,max.packet .data. size - 7 

— 7 bytes extra 

— ditto for puts 

VAL sp. max. removename. size IS sp. max. packet .data. size - 3 

— 3 bytes extra 

VAL sp. max. renamename, size IS sp. max. packet . data. size - 5 

— 5 bytes extra 

VAL sp, max. getenvname. size IS sp, max. packet . data. size - 3 

— 3 bytes extra 

VAL sp. max. systemcommand. size IS sp.max.packet .data. size - 3 

— 3 bytes extra 
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VAli sp , max . corerequest . size 
--3 bytes extra 



IS sp. max. packet .data. size - 3 



VAX sp. max. buffer .size IS sp. max. writebuffer .size 
— smaller of read & write 



— Result values 

VAX spr . ok 

— success 



<spr.) 

IS O(ByTE) 



VAL Spr . not . implemented IS l(BYTE) 

VAL spr . bad . name IS 2 (BYTE ) : 

-- filename Is null 

VAL spr. bad. type IS 3 (BYTE) : 

-- open file type is incorrect 

VAX spr, bad. mode IS 4 (BYTE) ; 

-- open file mode is incorrect 

VAX spr .invalid. streamid IS 5 (BYTE) : 

— never opened that streamid 

VAL spr .bad. stream. use IS 6 (BYTE) : 

— reading an output file, or vice versa 
VAX spr .buffer. overflow IS 7 (BYTE) ; 

— buffer too small for required data 

VAL spr .bad. packet. size IS 8 (BYTE) : 

— data too big or small for packet 

VAL spr .bad. origin IS d (BYTE) : 

— seek origin is incorrect 

VAL spr . full . name . too . short IS 10 (BYTE) : 

— a truncation of a filename would be required 
VAL spr.notok IS 127 (BYTE) : 

'-- a general fail result 



— anything 12S or above is a server dependent 
VAL spr. operation. failed IS 128 (BYTE) : 

— general failure 

VAX Spr. failed. Operation IS 129(BYTE) : 

— identical in meaning to spr .operation. failed due 

— to historical accident 



failure' result 



— Predefined streaias (spid.} 
VAL spid.stdin IS 0(IHT32) 
VAL spid.stdout IS 1(IHT32) 
VAL spid.stderr IS 2(IHT32) 

— Open types (spt,) 
VAX spt .binary IS 1 (BYTE) : 
VAX spt.text IS 2 (BYTE) : 

— Open modes (spm,) 
VAX spm. input IS 1 (BYTE) 
VAX epm. output IS 2 (BYTE) 
VAX spm. append IS 3 (BYTE) 
VAL spm. existing. update IS 4 (BYTE) 
VAL 6pm. new. update IS 5 (BYTE) 
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VAL Qpm, append. update IS €(BYTS) : 



"- Status values 
VAL sps. success IS 
VAL sps. failure IS 



999999999 (INT32) 
-999999999 (INT32) 



— Seek origins <spo.) 

VAL spo. start IS 1(INT32) 

VAL spo. current IS 2(1NT32) 

VAL spo. end IS 3(IHT32) 



— Version information (sph . , spo . , spb . ) 
Host types (sph.) 

values up to 127 are reserved for use by INMOS 
IS l(BYTE) 
IS 2 (BYTE) 
IS 3 (BYTE) 
IS 4 (BYTE) 
IS 5 (BYTE) 
IS 6 (BYTE) 



VAL sph. PC 

VAL sph.NECPC 

VAL sph, VAX 

VAL sph. SUNS 

VAL sph,S370 

VAL sph.B0X.SUN4 

VAL sph.BOX.SUN3a6 IS 7 (BYTE) 

VAL sph. BOX. APOLLO IS 8 (BYTE) 



— OS types (spo.) 
VAL apo.DOS IS 1 (BYTE) 
VAL spo. HELIOS IS 2 (BYTE) 
VAL spo. VMS IS 3 (BYTE) 
VAL spo. SUNOS IS 4 (BYTE) . 
VAL spo. CMS IS 5 (BYTE) : 

— values up to 127 are reserved for use by IHMOS 

Interface Board types (spb.) 

This determines the interface between the link and the host 



IS l(BYTE) 

IS 2 (BYTE) 

IS 3 (BYTE) 

IS 4 (BYTE) 

IS 5 (BYTE) 

IS 6 (BYTE) 

IS 7 (BYTE) 

IS 8 (BYTE) 

IS 9 (BYTE) 

IS 10 (BYTE) ; 

VAL spb.UDPLiNK IS 11 (BYTE) : 
— values up to 127 are reserved for use by INMOS 



VAL spb.B004 
VAL spb. BOO 8 
VAL spb.BOlO 
VAL spb.BOll 
VAL spb.B014 
VAL spb.DRXll 
VAL spb.QTO 
VAL spb,B015 
VAL spb.IBMCAT 
VAL spb.BOie 



— Command line 

VAL sp . short . coffimandline IS BYTE : 

— remove server's own arguments 
VAL sp . whole . commandline IS BYTE 1 : 

— Include server's own arguments 

— values for so.parse.commandline indicate whether 

— an option requires a following parameter 
VAL spopt . never IS : 
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VAL spopt. maybe IS 1 : 
VAL 3popt. always IS 2 : 

— Time string and d&te lengths 
VAL so. time. string. len IS 19 : 

~ enough for ''HH:MM:SS DD/MM/YYYY" 
VAL so.date.len IS 6 : 

— enough for DDMMYY (as integers) 

— Temp filename length 

VAX' so . temp , filename . length IS 6 : 

— 93.x chaxB will work on anything! 



C.2 Streamio constants 

— streamio . inc 

— Copyright 1989 INHOS Limited 

— Updated to match TDS3 strmhdr list; 4-Feb-91 SRH 
VAL St. max. string. size IS 256 : 

VAL ft. terminated IS -8 : — used to terminate a ksystream 
VAL ft. number. error IS -11 : 
PROTOCOL KS IS INT: 
PROTOCOL SS 
CASE 

at . reset 

at. up 

at , down 

at . left 

St . right 

at. goto; 1HT32; INT32 

Bt.ina.char; BYTE 

at . del . char 

at . out . string ; INT32 : : [ ] BYTE 

St. clear .eol 

at . clear . eos 

at . ins . line 

at. del. line 

Bt . beep 

St . spare 

at. terminate 

Bt . help 

at . initialise 

at. out. byte,- BYTE 

st.out.int; INT32 

at . key . raw 

at . key . cooked 

St . release 

at . claim 

st .endstream 

St. set. poll; INT32 
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C,3 Maths constants 



- mathvals . inc 

■ Copyright 1989 INMOS Limited 

■ Appended the error condition NaNs for the implementation of 

- the maths libraries; 4/Oct/90 3RH 
- ( { { Maths constants 



— {{{ REAL32 Constants 

VAl REAL32 INFINITY RETYPES #7FeOOO0O( 

VAL REAL32 MIKREAL RETYPES #00000001 ( 

~ 1.40129846E-45 

VAL REA132 MAXREAL 

~ 3.40282347E+38 

VAL REA132 E 

— 2.71828174E+aO 
VAL REAL32 PI 

— 3.14159274E+00 
VAL REAL32 LOGE2 

— 6.93147ia2E-01 
VAL REAL32 LOGlOE 

— 4.34294492E-01 
VAL REAL32 R00T2 

— 1.41421354E+00 
VAL LOGEPI IS 1.1447298858 (REAL32) : 

— log to the base e of pi 

VAL RADIAN IS 57 . 295779513 CRSAL32) : 

— the number of degrees in 1 radian 
VAL DEGREE IS 1 . 74532925199E-2 (REAL32) 

— the nuiDber of radians in I degree 
VAL GAMMA IS .5772156649 (REAL32} ; 

— Euler' a constant 



RETYPES #7F7FFFPF( 

RETYPES #402DF354( 

RETYPES #40490FDB( 

RETYPES #3F317218( 

RETYPES #3ED&5BD9( 

RETYPES #3FB504F3( 



INT32 ) 
INr32) 

IHT32> 

INT32> 
INT32 ) 
INT32 ) 
INT32 ) 
IKT32) 



— {{( implementation defined NaNa 
VAL REAL32 undefined. NaH RETYPES #7F80001D {INT32) 
VAL REAL32 unstable. NaW RETYPES #7F800008 (INT32) 
VAL REAL32 Inexact. NaN RETYPES #7Fa00004 (INT32) 
— })} 



— {{{ REAL64 Constants 

VAL REAL64 DINFINTTY RETYPES 
VAL REAL64 DMINREAL RETYPES 
~ 4.9406564584124654E-324 
VAL REAL64 DHAXREAL RETYPES 
~ 1.7976931348623157E+30e 
VAL REAL64 DE RETYPES 

— 2.71S2818284590451E+000 
VAL REAL64 DPI RETYPES 

— 3.141S926535897931E+000 
VAL REAL64 DL0GE2 RETYPES 
~ 6.9314718055994529E-001 
VAL REAL64 DLOGIQE RETYPES 
~ 4,3429448190325182E-a01 
VAL FEAL64 DR00T2 RETYPES 



#7FF0OO000000O000 (INT64) 
#0000000000000001 (INT64) 

#7FEFFFFFFFPFFFFF {INT64) 

#4005BFOA8B145769 (INT64) 

#400921FB54442D13 (INT64) 

#3FEe2E42FEFA39EF (INT64) 

#3FDBCB7B1526ES0E(INr64) 

#3FF6A09E667F3BCD (INT64) 
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~ l,4142135623730951E+000 

V3VX DLOGEPl IS 1 , 1447298358494001741 (REAL64) : 

— log to the base e of pi 

VAl DRADIAN IS 57 .293779513082320877 (REAL64) : 

— the number of degrees in 1 radian 

VAL DDEGREE IS 1 . 7453292519543295769^-2 (REAL64> : 

— the number of radians in 1 degree 

VAL DGAMMA IS . 57721566490153286061 (REAL64) : 

— Euler' s constant 

--{{{ implementation defined NaNs 

VAL REALe4 D undefined. Mall RETYPES #7FF0000200000000 (INT64) 
VAL REAL64 Dunstable. NaN RETYPES #7FF0000100000000 (INT64) 
VAL RRALe4 Dinexact .NaN RETYPES #7FF0000030000000 (IKT64) 

"}}} 



C.4 Transputer link addresses 



— linkaddr.inc 

— Copyright 1939 INMOS Limited 

— Transputer link addresses 

VAL linkO.in 13 4: 
VAL lixiJcO.out IS 0: 

VAL linkl.in IS 5: 
VAL linkl.out IS 1: 

VAL link2.1n IS 6: 
VAL liiik2.out IS 2: 

VAL link3.in IS 7: 
VAL link3.0ut IS 3: 



-- Transputer event address 
VAL event. in IS 6: 

C.5 Rates of the transputer clocks 

— ticks . inc 

— VI. 0, 09/May/90 

— Copyright 1990 INMOS Limited 

— These values are not for the A revision of the T414 

— (which is no longer supported ) . 
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— these values are the rates at which the two priority clocks 

— increment on the transputer 

VAL lo.ticJcs. per. second IS 1562S ( INT32 } : 
VAL hi. tic^cs. per. second IS 1000000 ( INT32 ) : 

VAL Xo.ticX. in. micro. seconds IS 64 ( INT ) : 

1000000 / lo. ticks .per. second 
VAL hi. tick. in. Micro. seconds IS 1 ( INT ) : 

— lOOOOOO / hi. ticks. per. second 



C.6 DOS specific constants 



-" msdos.inc 

— Copyright 1939 INMOS Limited 

— DOS command tags 

VAI. dos.send-block.tag IS OCBYTE) 

VAL dos. receive. block. tag IS 1 (BYTE) 

VAL dos. call. interrupt. tag IS 2 (BYTE) 

VAL dos.read.regs .tag IS 3(BYTE) 

VAL dos. port. write. tag IS 4 (BYTE) 

VAL dos. port. re ad. tag IS 5(SYTE) 



call . interrupt register layout 
VAL dos. interrupt .regs. size IS 40 : 



VAL dos. 
VAL dos. 
VAL dos. 

VAL dos. 
VAL dos. 
VAL dos. 
VAL dos . 

VAL dos. 
VAL dos. 
VAL dos. 



interrupt 
interrupt 
interrupt 
interrupt 

interrupt 
interrupt 
interrupt 
interrupt 
interrupt 
interrupt 



. regs . ax 
. regs . bx 
. regs . ex 
. regs . dx 
. regs . di 
. regs . si 
. regs . cs 
. regs . ds 
. regs . es 
.regs. S3 



IS 
IS 4 
IS 8 
IS 12 
IS 16 
IS 20 
IS 24 
IS 28 
IS 32 
IS 36 



— read. regs register layout 
VAL dos. read. regs. si^e IS 16 : 



VAL dos . read. regs .cs IS 

VAL dos , read . regs . ds IS 4 

VAL dos.read.regs.es IS 8 

VAL dos.read.regs .ss IS 12 



— buffer sizes (These depend on sp, max. packet. data. size) 
VAL dos .max. send. block. buffer . size IS 

sp. max. packet, data, size - 8 : 
VAL dos .max. receive. block. buffer. size 13 
sp. max. packet .data. size - 3 : 

— this is the smaller of send £ receive 
VAL dos. max. block. buffer. size IS 

dos .max. send. block. buffer. size : 
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This appendix defines the toolset implementation of Occam on the transputer. 
It describes how the compiler allocates memory and gives details of type map- 
ping, hardware dependencies and language. The appendix ends with the syntax 
definition of the language extensions implemented by the Occam compiler. 



D.I Memory allocation by the compiler 

The code for a whole program occupies a contiguous section of memory. When 
a program is loaded onto a transputer in a network, memory is allocated in the 
following order starting at Memstart: workspace; code; separate vector space, 
this is shown below; 



Higher address 
+ 



+ 
Lower address 

MemStart __ 



Free memory 



Vector space 



Code 



Workspace 



D.1.1 Procedure code 

The compiler places the code for any nested procedures at higher addresses 
(nearer mostpos int) than the code for the enclosing procedure. Nested 
procedures are placed at increasingly lower addresses in the order in which 
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their definitions are compJeted. For the code in the following example: 



PROC P{) 
PROC Q 

. * . code for Q 

PROC R () 

code for R 

code for P 



the layout of the code in memory is: 

MOSTPOS INT 

Higher address 



Code for Q 



Code for R 



Code for P 
Lower address 

MOSTNEG INT 

Note: this is a change from the previous release of the Occam compiler in the 
\MS D705/D605/D505 products. 



D.1.2 Compilation modules 

The order in which compilation modules are placed in memory, including those 
referenced by a #pragma linecage directive, is controlled by a linker directive. 
Modules are placed in priority order, with the highest priority module being placed 
at the lowest available address. 

Note: the compiler will attempt to optimise floating point routines such as 
REAI.320P and REAL320PERR by giving them a high priority. This can be 
overridden by using the compiler directive #pragma linkage in conjunction 
with the linker directive #SECTI0N, 
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D.I. 3 Workspace 

Workspace is given priority usage of the on-chip RAM, before the arithmetic 
iiandljng library. 

Workspace Is allocated from higher to lower address {i.e. the workspace for a 
called procedure is nearer mostneg int than the workspace for the caller). 
For example: 



PROC P 





. . . 


code 


here 






code 


PROC Q 





P 





In the above example when Q is called^ it will in turn call P. At the point labelled 
here, the data layout in memory will be: 



Higher address 



Lower address 



Workspace for Q 



Workspace for P 



In a PAR or PRI par construct the last textually defined process is allocated 
the lowest addressed workspace. For example: 



par 



PI 

P2 
P3 



the workspace layout for the parallel processes will be: 
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Higher address 



Lower address . 



Workspace for PI 



Workspace for P2 



Workspace for P3 



In a replicated PAR construct the instance with the liighest replication count is 
allocated the lowest workspace address. For example; 

PAR i = FOR 3 

P [i] 

the workspace layout for the parallel processes will be: 

Higher address | 

Workspace for P[0] 



Lower address 



Workspace for P[1] 



Workspace for P[2] 



Unless separate vector space is disabled, arrays larger than 8 bytes (apart from 
those explicitly placed in the workspace) are allocated in a separate data space, 
known as vector space. The allocation is done in a similar way to the allocation 
of workspace, except that the data space for a called procedure is at a higher 
address than the data space of its caller. 

Arrays whose elements are word-sized or longer, and which occupy 8 bytes or 
less, remain in workspace eg. 

[2]INT32 

will be placed in workspace. 

The variables within a single procedure or parallel process are allocated on the 
basis of their estimated usage. The variables which the compiler estimates will 
be used the most, are allocated lower addresses in the current workspace. 
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From within a called procedure the parameters appear immediately above the 
local variables. When an unsized vector is declared as a formal procedure 
parameter an extra VAL INT parameter is also allocated to store the size of 
the array passed as the actual parameter. This size is the number of elements 
in the array. One extra parameter is supplied for each dimension of the array 
unsized in the call, in the order in which they appear in the declaration. 

If a procedure requires separate vector space, it is supplied by the calling proce- 
dure. A pointer to the vector space supplied is given as an additional parameter. 
If the procedure is at the outer level of a compilation unit, the vector space pointer 
is supplied after all the actual parameters. Otherwise it is supplied before all the 
actual parameters. 



D.2 Type mapping 

This section defines all the Occam types and how they are represented on the 
each target processor. 

All objects are word aligned, ie. the lowest byte of the object is on a word 
boundary. For objects of type bOOl and byte, the padding above the object 
is guaranteed to be all bits zero: for ait other objects, the value of any padding 
bytes is undefined. 

Arrays are packed, ie. there are no spaces between the elements, (Note: that 
an object of type BOOL has one byte for each element). 

Table D.I summarizes the type mapping^ for further information on data types 
see Section 3 of the OCCam 2 Reference Manual 

Protocol tags are represented by 8-bit values. The compiler allocates tag values 
for each protocol from (BYTE) upwards In order of declaration. 

Values accessed through retypes must be aligned to the natural alignment for 
that data type; BYTEs and BOOLs may be aligned to any byte; INT16S on a 32 
bit processor must be aligned to a half-word boundary and all other data types 
must be aligned to a word boundary. This will be checked at run-time if it cannot 
be checked at compile time. For example: 



[20] BYTE array: — This will ba word aligned 

— Run-time check ia 

— inserted 

— Run-time chock is 

— inserted 
IKT32 z RETYPES [array FROM 8 FOR 4] 



INT32 X RETYPES [array FROM 1 FOR 4] 
INT32 y RETYPES [array FROM i FOR 4] 



No run- time check 
inserted 
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Type 


Storage 


Range of values 


BOOL 


^ byte 


FALSE, TRUE 


BYTE 


1 byte 


to 255 


INT16 


2 bytes 


-32768 10 32767 


INT32 


4 bytes 


■2.147,483.648 to 


INT64 


8 bytes 


2,147,483,647 
-2^ to (2^-1) 


INT 


4 bytes 


■2.147.483.648 10 


On T400/T414/T425 T800/TS01/T805 




2.147.483,647 


INT 

On T212/T222rr225 W212 


2 bytes 


-32768 to 32767 


REALS 2 


4 bytes 


IEEE single precision 
fornnat 


REAL64 


8 bytes 


IEEE double precision 
format 


CHAN 

on T400/T41 4/7425 T800/T801/T805 


8 bytes 


Channels are 
implemented as a 


CHAN 
onT212/T222/T225M212 


4 bytes 


pointer to a channel 
word. 


PORT OF D 


as for D 


TIMER 


none 



Table D.I Occam datatypes 



Channels may be RETYPEd. This allows the protocol on a channel to be 
changed, in order to pass it as a parameter to another routine. This facility 
should be used with care. 



D.3 Hardware dependencies 

• The number of priorities supported by the transputer is 2, (i.e. high and 
low), so a PHI PAR may have two component processes. The compiler 
does not permit a PRI par statement to be nested inside the high pri- 
ority branch of another. This is checked at compile time, even across 
separately compiled units. 

• The low priority clock increments at a rate of 1 5 625 ticks per second, or 
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one tick = 64 microseconds (IMS T212, T222, T225, M212, T400, T414. 
T425, T800, T801 and T805). 

• The high priority clock increments at a rate of 1 000000 ticks per second, 
or one tick = 1 microsecond (IMS T212. T222, T225, M212. T400, T414, 
T425, TSOO. T801 and T805). 

* TIMER channels cannot be placed in memory with a place statement. 



D,4 Language 

• The following directives are supported: #INCLUDE, #USE, #COmment. 
#IMP0RT, ftOPTiON and tPRAGMA. For more information about com- 
piler directives see part 1, section 25.10. 

• The following statements are supported: PLACE name IN yecspace, 
PLACE name IN WORKSPACE and pIiACE name AT workspace n 

• The address used in a place allocation Is converted to a transputer 
address by considering the address to be a word offset from mostneg 

INT. 

For example, In order to access a BYTE memory mapped peripheral 
located at machine address #1234, on a 32-bit processor: 

PORT OF BYTE peripheral : 

PLACE peripheral AT (#1234 X (MOSTNEG INT)} » 2 : 

peripheral ! (BYTE) 

• The numbers used as place addresses are word offsets from the bottom 
of address space. 

PLACE scalar channel AT n. places the channel word at that address, 

place array of channels kt n, places the the array of pointers at that 
address. 

Note: PLACE array of channels AT n maps an array of pointers to chan- 
nels. This is a change from D705/D605/D505 releases of the Occam 
compiler where this allocation was used to place an array of channels. 

• A channel declared as CHAN OF ANY can be passed as an actual pa- 
rameter in place of aformal channel parameter of anyprotocoL A channel 
of a specific protocol cannot be passed in place of a formal channel pa- 
rameter of CHAN OF ANY. Communications on a channel declared as 
CHAN OF ANY must be identical at both ends of the channel, 
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• The keywords GUY and asm introduce a section of transputer assembly 
code. 

• The keyword inline may be used immediately before the proc or 
FUNCTION keyword of any procedure or function declaration. This will 
cause the body of the procedure or function to be expanded inline in any 
call, and the declaration will not be compiled as a normal routine. Note: 
the declaration is marked with the keyword, but the call is affected. This 
means that you cannot inline expand procedures and functions which 
have been declared by a #USE directive: to achieve that effect you may 
put the source of the routine in an include file, marked with the inline 
keyword, and include it with an #include directive. 

Examples: 

INT inline function sum3 (VAL INT x, y, z) 
IS X + (y + z) : 



INLINE PROC seterror () 
error := TRUE 



• The compiler accepts the string escape characters as described in sec- 
tion I of the Occam 2 Reference Manual. The compiler also accepts 
'*!' or '*L' as the first character of a string literal . This is expanded 
to be the length of the string excluding the character itself. For example 
stringl and string2 are identical: 

VAL stringl is ' '*lFred" : 
VAL string2 is ' '#04Fred' ' : 

The use of '*!' is iilegal if the string (excluding the '*!') is longer than 
255 bytes, and will be reported as an error, 

• Multidemensional arrays defined by a retypes definition may have one 
element whose value is not explicitiy stated. This may be any one of the 
elements. For example: 

[6] INT a, f : 

[2] [ IINT b RETYPES a : 
[ ] 13] INT c RETYPES f : 

[24] INT d : 

[2] t ] [6] e RETYPES d : 

Note this is a change from the previous implementation of the compiler 
in the IMS D705/D605/D505 products, and removes the restriction that 
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the inner-most element of the array could not be left unspecified. 

• The compiler places restrictions on the syntax which is permitted at the 
outermost level of a compilation unit; i.e. not enclosed by any function 
or procedure. 

- No variable declarations are permitted. 

- The file must contain at least one PROC or function; a null 
source file is illegal. 

- No abbreviations containing function calls or valOFs are allowed, 
even if they are actually constant. For example: 

VAIi X IS (VALOF 
SKIP 

RESULT 99 
) ; -- This is illegal. 

VAL m IS max (27, 52) : — This is also 

— illegal. 

• There is no limit on the number of significant characters In identifiers, 
and the case of characters is significant. 

• CASE statements are implemented as a combination of explicit test, bi- 
nary searches, and jump tables, depending on ihe relative density of the 
selection values. The choice has been made to optimise the general 
case where each selection is equally probable. The compiler does not 
make any use of the order of the selections as they are written in the 
source code, 

• No assumption can be made about the relative priority of the guards of 
an ALT statement; if priority is required, you must use a PRI ALT. 

• The compiler expands tabs in source files to be every eight character 
position. Tabs are permitted anywhere in a tine except within strings or 
character constants. 

• If a name is used more than once in a singte formal parameter list, the 
fast definition is used. 
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D.5 Summary of implementation restrictions 

• FUNCTIONS may not return arrays, not even with fixed sizes. 

• Muftipfe asSEgnment of arrays of unknown size is not permitted. 

• Replicated par count must be constant. 

• There must be exactly two branches in a PRi par 

• Replicated pri pars are not allowed. 

• Nested PRI pars are not permitted. 

The D705/D605;D505 releases of the OCcam compiler did not check 
this condition correctly, allowing some erroneous programs. Such code 
should be modified as follows: 

PRl PAR 

high priority process 

code which includes a PRI PAR 

This can be re-wrltten as the following: 

PAR 

PRI PAR 

high priority process 

SKIP 

code which includes a PRI PAR 

• Table sizes must be known at compile time, for example: 

PROC p ([JINT a, []INT b) 

VAL [] []INT X IS [a] : -- this is 

— illegal 
VAL [JINT y IS b : — this is 

— legal 

• Constant arrays which are indexed by replicator variables are not consid- 
ered to be constants for the purposes of compiler constant folding, even 
if the start and limit of the replicator are also constant. This restriction 
does not apply during usage checking. 

• Maximum number of nested include files is 20. 

• Maximum filename length is 128 characters. 
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a Maximum 256 tags allowed in PROTOCOLS. 

• Maximum number ot lexical levels is 254, (Nested PROCs and replicated 
pars). 

• Maximum number of variables in a procedure or function is 2048. 

If this limit is reached, it should be remembered that any OCCam code 
can be 'wrapped up' into a separate procedure, and can still access 'non- 
local' variables correctly. This will reduce the complexity of an enclosing 
procedure and should allow the program to be compiled. 

For example, suppose that the foilowing program reaches this limit: 

PROC p C) 

variable declarations in here 
SEQ 

lots more variable declarations 
SEQ 

first block of code 

lots more variable declarations 
SEQ 

second block of code 



This could be modified to read as follows: 

PROC p C) 

variable declarations in here 
SEQ 

PROC locale () 

lots more variable declarations 
SEQ 

first block of code 

localOO 

PROC locall 

, . , lots more variable declarations 
SEQ 

second block of code 

locall 
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D.6 Syntax of language extensions 

This section describes the syntax of the following extensions to OCCam: 

• ASM 

• PLACE name AT WORKSPACE n 

• PLACE name in workspace 

• PLACE name IN vecspace 

• INLINE 

• The non-printable character '*!' or '*L'. 
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D,6,1 ASM statement 

The syntax of the ASM construct takes the following format: 



process 
asm. construct 

BsmMirective 



labeldef 

primary. op 

load, or, store, op = 

branch.op 

SGCondary-op 

pseudo-op 



asm.exp 



asm. construct 

ASM 

{ asm.directJve } 

primary.op constant. expression 

ioad.or.store.op name 

branch.op :labet 

secondary.op 

pseudo.op 

labeldef 

: label 

direct instruction 
prefixing instruction 

OPR 

LDL I LDNL | LDLP | LDNLP 
STL 1 STNL 

J I CJ I CALL 

any transputer operation 

LD asm.exp 

LDAB asm.exp , asm.exp 

LDABC asm.exp , asm.exp , asm.exp 

ST element 

STAB element , element 

STABC element , element , element 

BYTE {, constant.expression } 

WORD {, constant.expression } 

LDLABELDIFF -.label- : label 

ADDRESSOF element 
expression 
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Appendix B lists the transputer instructions and operations supported by the 
restricted code insertion facility. All the instructions [isted can be inserted into 
Occam programs using the ASM construct. Note: instructions should be speci- 
fied in upper-case. 



D.6.2 PLACE Statements 

The syntax of the PLACE statements extends the definition of an allocation as 
defined in the 'Occam Z Reference Manual': 

allocation = place name AT expression 

I PLACE name at workspace expression 

I place name IN workspace 

I place name IN vecspace 



D.6.3 INLINE Statement 

The INLINE statement extends the syntax of a definition as defined in the 
'Occam 2 Reference Manual': 

definition = PROTOCOL name IS simple. protocol: 

I PROTOCOL name is sequential. protoayt: 
I PROTOCOL name 
case 

{ tagged.protocol } 

I /Inline; PROC name { {o . formal}} 
procedure, body 

I {i , primitive type } /Inline/ function name 
( {o , formal } ) function, body 

I {i , primitive type } /Inline; function name 

( {o , formal] ) IS expression.list : 
I specifier name retypes element : 
I VAL Specifier name RETYPES expression : 
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D.6.4 *1 or *L character 

The syntax of the non-printable character '*', as defined in section i of the 
'Occam 2 Reference Manual' has been extended. The first character of a literal 
string may now take the value **!' or '*L', which is used to represent the length 
of the string, excluding the character itself. 

The characters *, ' and " may be used in the following form: 



*c 


*c 


carriage return 




- *#0D 


*1 


*L 


string length 




< *#FF 


*n 


*N 


newline 




= *#0A 


*t 


*T 


tab 




= *#08 


*s 


*S 


space 




= *#20 


■kf 




quotation mark 






*" 




double quotation 


mark 




• * 




asterisk 







Any byte value can be represented by *# followed by two hexadeximat digits. 
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language definition 



This appendix defines the syntax of the occam configuration language. 

A configuration program file contains a sequence of specifications. These spec- 
ifications should include one hardware description and one software description. 
There will in generai be at least one node declaration, and optionally edge dec- 
larations and arc declarations. An optional mapping may appear either before 
of after ihe software configuration, but after the declaration of any nodes, edges 
or arcs which it references. These njtes are applications of the normal occam 
scope rules. 

This syntax should be considered as extending the syntax of occam. 

The # INCLUDE mechanism nnay be used to incorporate hardware descriptions, 
software descriptions, or any other source text from other files. 



E.1 New types and specifications 

specification = hardware.description 

I software, description 

I mapping 

[ node, declaration 

I edge.declaration 

I aradeclaration 

I channel.aflocation 

node. declaration = { o [ expression ] } node node.name : 
edge.declaration =^ { o [ expression ] } edge declared.edge.name : 
aradeclaration ^ { o [ expression ] } ARC arc.name ; 

The syntax adds the new primitive types NODE, edge and ARC, and structures 
CONFIG, NETWORK and MAPPING to the occam language. 

NODE declarations introduce processors {nodes of a graph). These processors 
are physical if their type and memory size attributes are defined as part of the 
hardware description, and /op/ca/ otherwise. 

EDGE declarations introduce external connections of the hardware description. 

ARC declarations introduce named connections (arcs of a graph). Each arc 
connects two edges, which may be attributes of nodes, or declared edges. Con- 
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nections need only be named if it is required to force a particular mapping of 
channels, or if names are required to aid debugging. 



E.2 Software description 

A CONFIG declaration introduces the software description as an occam process. 
Additional specifications and processes are added to occam: The processor 
name in a processor statement may be a physical processor name or the 
name of a logical processor which is mapped onto a physical processor. A 
channel allocation may allocate up to two channels onto a named arc of the 
network. 

software, description = { specification } 

CONFIG [config.name] 
process 



specification = channel, allocation 

I node.declaration 
channel.ailocation = place { i , channeLname { o [ subscript ] }} ON 

arc 
process = processor p/'ocessor.f7ame { o [ subscript] } 

process 
arc = arc.name { o [ subscript ] } 



E.3 Hardware description 

The NETWORK keyword introduces a hardware description, an optionally named 
structure which describes the types, connectivity and attributes of previously 
declared processor nodes. Connections are defined in connect statements. 
Attributes are given values in SET statements. The attributes of a processor 
node include an array of edges which are its links, a string which defines its 
processor type, and an integer which is the memory size in bytes. 

Connections and attribute settings may be combined in any order using the DO 
constructor, including replication and conditionals. For each node which has a 
type defined to be a processor the attributes with predefined names type and 
memsize must be set once only. The connections connect declared edges and 
edges of nodes, which have the predefined attribute name link. The boolean 
attribute root may be set to TRUE for only one node in a network without a 
connection to the predefined edge HOST. The attribute romsiae defines the 
size in bytes of read only memory on a node. Attributes are referenced by 
subscripting node names with attribute names in brackets. 
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hardware, description 



= { spedficatiof] } 

NETWORK [ network.name ] 
networi<Jtem 



specification = 



node.decfaration 

edge.declaration 
arc-declaration 



network.item 



connection. item 
setting. item 

DO 

{ network.item } 

DO replicator 

networkMem 
conditional, network, item 

SKIP 
STOP 

abbreviation 
networkJtem 



conditlonai. network.item = 

network.choice 

guarded, network, choice = 



IF 

{ network.choice } 
guarded, network.choice 
conditionaLnetwork.item 
boolean 

network.item 



connection, item 

with.dause 
edge 



setting.item 

attribute, assignment = 

attribute 

attribute, value 



CONNECT edge to edge [ with.dause } 
WITH arcname 

declared.edge.name { o [ subscript ] } 
node. name { o [ subscript ] } [ attribute.name ] 
{ [ subscript ] } 

= SET node.name { o [ subscript ] } 
( attribute. assignment ) 
{ 1 , attribute } := { i , attribute. value } 
attribute.name {o , [ subscript ] } 
expression 
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E.4 Mapping structure 

The keyword MAPPING introduces an optionally named mapping staicture which 
may be either before or after the software description. 

A mapping may be used to associate logical processors with physical processors 
and channels with arcs of the hardware network. Mapping of channels is optional 
except in the case where one end of the arc is an external edge. The configurer 
will normally choose a mapping from its knowledge of the connectivity of the 
hardware and the implied connectivity derived from the use of channels as in the 
software description. 

The mapping may include code mappings and channel mappings. A logical 
processor may appear on the left hand side of only one mapping item. A physical 
processor may appear on the right hand side of one or more mapping items. A 
code mapping may include a priority clause which will determine the priority at 
which the process will run. The arc in a channel mapping must connect the 
nodes onto which the processes using the channels are mapped. The effect 
of channel mappings is identical to the corresponding channel allocations which 
may appear in the software description. 

mapping = { specification } 

MAPPING [ mapping.name ] 
map.item 



specification = node. declaration 

mapJtem = code. mapping 

I channeimapping 

I DO 

{ map.item) 
I DO replicator 
map.item 
I conditional, map. item 
I SKIP 
I STOP 
I abbreviation 

mapJtem 
I setting.iiem 
conditional, map.item = if 

{ mapping.choice } 
mapping, choice = guarded, mapping, choice 

I conditional, map.item 
guardedmapping.choice = boolean 

map.item 
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code.mapping 

priority, clause 
processorJist 
processid 

processor, name =* 
node 

channel. mapping = 

channel.list 

channelid 

arc 

setting. item 

attribute.assignment 
attribute 
attribute. value 



MAP processor Jist OUTO node [priority.dause] 

PRI expression 

{ 1 , processid } 

processor, name { o t subscript ] } 

node, name 

node, name { o [ subscript ] } 

MAP channel.list ONTO arc 
{ 1 , channelid } 
channel.name { o [ subscript ] } 
arc. name { o [ subscript ] } 

SET node.name { o [ subscript ] } 
( attribute.assignment ) 
= { 1 , attribute } := { i / attribute. value) 
= attribute.name { o M subscript ] } 

expression 



E.5 Constraints 

The following constraints apply to all configurations: 

• All physical processors whose types are set must be connected to each 
other, 

• Any physical processor whose type is set must have its memsize set. 

• Logical processors may only be mapped onto physical processors whose 
type has been set. 

• Channels connecting processors of different word size must not use pro- 
tocols based on the type int. 

• A priority expression must evaluate to (high) or 1 (low). 
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E.6 Changes from the IMS D705/D605/D505 products 

The following changes are necessary to convert a configuration from the lan- 
guage used by previous INMOS configurers: 



Channel allocations to physical hardware iink addresses should be removed. 

PROCESSOR statements should be modified to reference (logicai or physfcal) 
processor names, instead of processor numbers. 

Each physical processor in the configuration should be declared in a node 
decJaration. 

Each external connection from the network should be declared in an edge 
declaration. 

A hardware description setting attributes of all hardware processors and defin- 
ing connections between them must be written. 

If fogicaf processors have been introduced then a mapping of these onto the 
physical processors must be written. 

Arcs connecting to external edges should be declared. Channels using these 
arcs should be mapped. 

Check that #USE lines refer to files containing linked code. 
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F.1 Introduction 

special loading procedures can be created for the program and used in place 
of, or in addition to, the standard INMOS bootstrap. The file containing the new 
bootstrap is specified by invoking the collector with the 'b' option. 

User defined bootstraps must perform all the necessary operations to initialise 
the transputer, load the network, and set up the software environment for the 
application program. 

Bootstraps are output to the program bootable file as the first section of code in 
the bootable file. The bootstrap, consisting of the primary and secondary boot- 
strap sequences, is followed by the standard INMOS network loader program, 
which is output in small packets, each packet consisting of a maximum of 60 
bytes. The tast packet of the network loader is followed by a length byte of zero. 

In most cases a custom bootstrap will interface directly with the standard IN- 
MOS Network Loader, which places various pieces of code and data within the 
transputer memory in a controlled way. However it is possible to skip the stan- 
dard loader by sinking its code packets and following the commands used by 
the network loader that are output after the network loader. 

The general format of a custom bootstrap is a concatenated sequence of boot- 
strap code segments each preceded by a length byte. The sequence can be 
any length. The bootstrap program must be contained in a single file. 



F.1.1 The example bootstrap 

The example bootstrap loader provided on the toolset examples directory is 
a combination of several files used in the standard INMOS bootstrap scheme. 
The files have been combined into a single file to illustrate how to create a user- 
defined bootstrap; the functionality is the same as that used in the the standard 
INMOS scheme based on multiple files. 

The program Is written in transputer code and consists of two parts: 

Pfimary bootstrap - performs processor setup operations such as initial- 
ising the transputer links 

Secondary bootstrap - sets up the software environment and interfaces 
to the Network Loader. 
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Transfer of control 

The calling sequence in the standard INMOS scheme is as follows: 

The primary loader calls the secondary loader, which then calls the Network 
Loader. When the Network Loader has completed its work control returns to 
the secondary loader, which calls the application program via data set up by the 
Network Loader. 

Custom bootstraps Should follow the same sequence. 



F.1.2 Writing bootstrap loaders 

Bootstrap loader programs should be written to perform the same operations 
as the standard scheme, that is, hardware initiafisation, setting up the software 
environment, and calling the Network Loader. If you skip the Network Loader by 
sinking its code bytes then you must ensure its function is reproduced in your 
own code. If you do use the Network Loader you must ensure the interface 
to it is correct by setting up the invocation stack. The method by which this is 
achieved can be deduced from the example program listing, 

If you wish to make only a few small changes to the standard loader, for exam- 
ple, insert code to initialise some D-to-A convertors, then the example code can 
be used and the required code can be inserted between the Primary and Sec- 
ondary Loader code as an additional piece of bootstrap code in the sequence 
of bootstraps. The rest of the code can be used as (t stands. 

If you decide to devise your own loading scheme and rewrite the Primary and 
Secondary Loaders then you should be familiar with the design of the Transputer 
and its instruction set. For engineering data about the transputer consult the 
'Transputer Databook' and for information about how to use the instruction set 
see the 'Transputer Instruction Set: a compiler writer's guide'. 
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F.2 Example user bootstrap 



{C^) IninoB 19S9 

Ascvinbly fila for tbs Genvric Friinary bOOtttrap TA SALT mod* 



loop Indue 
loop Goujii: 

■tart of loadAr 
loadoE block lan^th 
■tart of naxt block to load 
link boot*d from 
wock apaofl of loadled cad^ 
Ectiirn Bddra^s from loadar 
IS : *' VrorJtspac* Uflad by both 
pr^ainbla and Loader 
copy of Hinint 

— let p*rMtt to loadar (Mlnlnt) 
-- 2nd pArftmat«E to loAd«r 
— 3nd paramatar to load*r 
4th paraioater to loa.dar 

- 5tb parainotar to loader 
' Cth parajsatar to loader 

7th par3in«t«r to loadar 

rafar«noad frOra «ntry point 
rA£«rnac«d from D«ta point 
•tart of boot pirt 2 

— *he initial workapac* roqalrement 1« found by raiding tha worJcspaoe 

— roquiramBnt from tha loadar \occam\ and subtracting th« alza of tha Morkspaca 

— uB«d by both tha loader ftnd tha bootatrap (\v»rb| tamp.workspacej ) , rhla valu« 

— is Increcnentad by 4 to acconmodata th« MorkBpac* adjustmant by tb« call 
~ instruction usad to pr«BaEV6 tha procassor ragiatar*. 

— initial. adjuatmant ;■ (la*d*r.work6paca + 4) - tiMnp . workapac* 

-- occao vork apaca, -V 4 fOE call to aav* ragiatara, - adjaflti»ant mada 
-- when «nt«ring ocean. Huat b« at laaat 4 

— IF 

Initial. adjustment < 4 
initial. adjustmant := 4 

TRUE 
SKTP 

— tat up Hork apace. Bava regiatarB^ 

— sav* HemStart and NotPrOCfiaa 

align 

byta (Endprlmary -Primary) — Langth oC tha primary bootatcap 
Primary: 
global Primary 



vu. 


BAsa 


IS 


1 




VAL 


CODHT 


IS 


2 ; 


VAL 


LOAD START 


IS 







VAL 


LOAD LENGTH 


IS 


1 




VAL 


NEXl:_ADDRESS 


IS 


2 




VAL 


BOOTLIHK 


IS 


3 




VAL 


MEXT_WeTR 


IS 


4 




VAL 


RETUTUJ_ADDHESS 


IS 


5 




VAL 


TEMPjaOEKSPACE 


IS 


RETURH_W:)D1 


VAL 


NOTPROCESS 


IS 


fi : 


VAL 


Limes 


IS 


KOTPROCESS 


VAL 


BOOTLIHK_IN_PARAM 


IS 7 - 


VAL 


BOQTLINK_OUT_PJiJUkM 


IS a ■ 


VAL 


MEMORY 


IS 


9 : 


VMi 


EXTERNAL ADDRESS IS 1& : 


VAL 


ENTRY POINT 


IS 


11 : 


VAL 


DATA POIHT IS 


12 


— 


VAL 


ENTftY_ADDHESS 


IS 


13 




VAL 


DATA ACDES£S 


IS 


14 




VAL 


HEMS I ART 


IS 


IS 





ajw IWITIAL_ADJUSrMENT -- ■«• abov« (la 20) 

call — aava raCflatara 



Idc 
1dpi 
AddrOi 
atl 


__Start - AddrO 
MEMS TART 


-- diatanc* to Start byta 

— addr«K of start 

— aava Cor latar uaa 


ELint 

Rtl 


KOTPROCESS 


-- aava for latar uaa 



72 IDS 276 02 March 1991 



212 F Bootstrap loaders 



— lniti«llB« proammm qu«u«t uid claar arror 

Idl dOTPROCESS 

■tlf — re««t low priority quava 

Idl NOrPROCESS 

•thf — rasat high priority queue 

— u«* clrlialterr hara to create boot strap for KEDUCSD application 

aathalterr -- set halt on arror 

testerr — read and clear error bit 

— Initialise T8 *ri:or and rounding 

Idl MEHSTBET ~ CbocJt If procaaaor ha* floating pplnt unit by 

Idl HOTPROCESS — ciaeJcing if (mematart >< mint) >« #70 

xor 

Idc #70 — ManiBtart for TS, TB 

rav -- E ■ #70, A - (Meinatart >< MINT) 

gt 

eqc 

cj Nofpa 

fptectarr -- floating cbacJc and. clear error instruction 

Mdfpu: 

— inltlallaa link and event Korda 

Ida 

Btl BASE — Index to worda to Inltlaliae 

Idc 11 — no. word* to initialice 

•tl COUNT — count of Hocda left 

St art loop: 

Idl WOTPROCESS 

141 BME — index 

Idl HOTEROCE5S 

vBub — point to next addraaa 

Btnl — put VotProcasa into addraased Mord 

Idlp BASE ~ addraaa of loop control info 

Ida Xndloop - Btartla^p — return jump 

lend -- go back if more 
Endloop : 

-- set up aoma loader paraiiiataFa. See the parameter 

— otruGt-ar* Of the loader 
Idl HEM5TART — cle&r data and entry addresaea 



— addres« of entry word 
-- store In param 7 

— address of entry word 

— atore in param £ 

— buffer offset In param 5 

-- Btart o£ memory 
-- Btoce in param 4 

-- copy of boot link 
1 — Btora in parani 2 

— How find the oorraapending output linJc and place In tba paranetez 

Idl BiXULIMX 

l^lp -4 — calculata the output link addresa 

■tl BOOH,INK_OUT__PAKAM -- atore in param 3 
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atl 


DATA^MDRESS 


Idl 


MEMSIAAT 


Btl 


ENTRr_ADDKESS 


Idlp 


DJlTA_ADDHESS 


atl 


DATA_POINT 


Idlp 


ENrHY_ADDRESS 


atl 


EKr&Y_POIKT 


Idl 


NOT PROCESS 


•tl 


EITEEHAL_AI3DE£SS 


Idl 


HEMSTART 


*tl 


MEMORY 


Idl 


BOOTLINK 


Btl 


BOOTLIHK IN PARAl 



F,2 Exampte user bootstrap 
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load bootloader ovar bootstrap 

coda must be 2 bytes ahoctar than bQotstcap 
Idlp LOJU)_LENGTH — p»ctat siza ward 

\Al BMTLIMK -- iddraes of lint 

Idc 1 — byt4» to lo»d 

In — Input l*ngth byttt 



Idl HEHSTARr 

Idl BOOILINK 

Idl L0AI3 LENGTH 



-- Area to load bootloadar 

— iddraas of linlc 

— n)«s«»ga iangth 

— Input boetloader 



•nter coda jvat loadad 



pfix 





pfix 





pfljc 





pIlX 





pflx 





pfix 





pfix 





pfix 





pfix 





pfix 





pfix 





Idl 


tffiHSTARl 


ac*ii 





— For tba naxt boot&trap to be 2 bytaa bigger 



•t&rt of loaded codA 
•ntar bootloadax 



align 



Endpzimary : 



— (a) Inino* 1969 

— ABaambly file for the ganaric jaconda.zy loadar TA IQHORE toode 



VAL 


aisE 


IS 




VM. 


COUST 


IS 




VAL 


LOAD START 


IS 




VAi> 


LOAD LENGTH 


IS 




VAL 


NEXT_ADDRESS 


IS 




VAL 


BOOTLIHK 


IS 




VAL 


NEXT_HPTR 


IS 




VAi 


EETDRH_ADER2SS 


IS 


5 


VAI< 


T£MP_ttORKSPACE 


IS 


m 


VAL 


HOTPROCESS 


15 


c 


VAL 


LINKS 


IS 


N< 


VAL 


BOOTLINK IS PARAM 


IS 


VAL 


BOOTLIHK our PARAH 


IS 


VAL 


MEMORY 


IS 


» 


VAL 


BUFFER 


IS 


10 


VAL 


WEXT_gOlNT 


IS 


11 


VAL 


ENTRY POINT 


IS 


12 


VAL 


DATA POINT 


IS 


13 


VAL 


ENTRY_AI1DRESS 


IS 


14 


VAL 


DATA ADDRESS 


IS 


15 


VAL 


NEXT ADDRESS 


IS 


16 


VAL 


HEMSTART 


IS 


17 


VAL 


PACKKT t^NGTtl 


IS 


12 


VAL 


OCCAM WORKSPACE 


IS 


IS 



— loop index 
-- loop aount 

-- start of loader 

— loader bloak leng-th 

— start of next block to load 
-- ltn)t booted from 
-- vorJc apace of loaded aode 
-- return address from loader 

RETURN jfcDDRESS : — woEkaptce \jaed by both 
-- praaiiible and loader 

— copy Of Mlnlnt 
HOTEROCESS ; — lat param to loader (MinlAt) 

-- 2nd parameter to loader 
-- 5nd parameter to loader 

— 4th pacamatez to loader 



etb parameter to loader 
7th parameter to loader 
Eltb parameter bo loader 
referenced from entry point 
refereaced from Data point 
referenced from Nexat point 
■tart of boot part 2 
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bytft (SndAscoadary-Sacondar:^] 
Secondary: 
g^Iobal Secondary 
— lnltl«.LlB« bootloader wor}tBpa.c* 



Length of ch* AAOondt^y baoAtEAp 



Idc 
Idl^ 
bsub 
■tl 


PACKEI_LEHGrH 
MSHSTART+I 

SEyT_AD DRESS 


Idl 


HEXr_ADDBESS 


Idlp 


HEMSTARTtl 
MEMORY 


Idlp 
atl 


TEMP_HORKSPACE 
KEXT_MPrK 


Idc 
«tl 



BUFFER 


Idc 
stl 


LOAD I^HGTH 


Loadcode : 
Idl 
■tl 


HEXT_ftEDRBSS 
LOAD START 



buff*r Biz« 

bu££*r atart addrAa* 

*nd of buffer addr«Ba 

■taft of azaa to load loadac 



buffaC Btart addrvas 
Earliest place to load 



' pointer to loadar' a work apace zero 
work epaca polntar of loaded cod* 



Buf£«r offset from Buffer start 



clear bytes to load 



-- addrasa to load loader 
— currant load point 



— load cod« until terminator 
Startload: 

Idlp LOAD_LENGTH 



Idl 


BOOTLINK 


Idc 


1 


in 




Idl 


LOAD LENGTH 


cj 


Endload 


Idl 


HEXT_aDDHESS 


Idl 


BOOTLINK 


Idl 


LaAD_LENGTH 


In 




Idl 


LaAD_LENGTH 


Idl 


HEa:T_aDDRESS 


bsub 




atl 


HEXT_ADDRESS 


J 


Startload 


Load: 





— packet length 
-- address of link 
-- byt«8 to load 

— input length byte 

— ma&saga length 

— quit if bytes 

" start of area to load loader 
-- address Of link 

— mefisage length 
-- input code block 
-- iMReage length 
-- area to load 

-- new area to load 

— aave area to load 

— go back for next block 



^- initialise return addreaa and enter loaded code 

Idc Eaturn - Addrl — offe*t to return address 
1dpi — return addxeas 

Addrl : 

stl KETIJRN ADDKESS — save in WO 



Idl 
stl 



EOOTLINK 

OCCAM WORKSPACE 



Idl HEXT_JHPTR 

gajw 

Idnl l.OM«_START 

gcall 



' Get boot link and aave for later 
' Save in area that will not b« used 
■ by network loader 

' wapaca of loaded code 
' set up his work apace 

addrass of first load packet 

enter loaded code 
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— Now aat up invocation stack for t!ti« Inlt_ByjEt6ai 

*jir (T£Uff_ttOftKSPACE 4 4) — rftsst Hork space after return 

— get back boot link 

get addreee of proceasoc structure 



convert to reitl entry addrev* 



Idl 


OCCAM WORKSPACE 


stl 


BOOTLIHK 


Idl 


DArAJU}DRESS 


Idl 


KZMORY 


beub 




stl 


DATA_POIHT 


idJ. 


ENTRY ADDRESS — 


Idl 


MEMORY 


bfiub 




etl 


LOAD_SIART 


Idl 


NOTBROCESS 


ttl 


KEXT_EOIHI 


Idl 


MEMORY 


atl 


BUFFER 


Idl 


EHTRY^ADDRESS 


atl 


TEME_WORKSPACE 


Idl 


NEXT ADDRESS 


Idl 


KEHORY 


bvub 




Etl 


NEXT_AD DRESS 


Idc 





stl 


LOAD__LEMGTH 


Idlp 


NOT PROCESS 


stl 


NEXT HPTR 



' make DAEIL base offset and CODS base offsat the saine 



- Set up entry point 

-- convert returned address of next seqiuance to 

— a real address 



-- clear bytes to load 
— Top of tenip workspace used by bootloadar 



start clock 



Idc 
sttiimr 



align 
Endsecondary : 



— Qo back for more and over write the network loader 
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F,3 The INMOS Network Loader 

The following code, written in Occam, represents the standard network loader 
program used by IMMOS. 



— T£llB generic loadar is wrlttan and Bhould b* compllad with out &ny processor typa 
-- dep«ndanclaA. TbAt la tha saim obj,Bct cods la ue«d 6V6n i£ the procaeaor it ona of 
-- th« sixteen bit variety 



PROC Lo 


>dar ([4JCHAH 


OP ANY 


liiL}ca, 




CHAH OF 


AHY 




boatlink.in, bootllnJc. out. 




[41BYTE 






aaaciory. 




VAL INT 






Buffer . addrasa. 




TNT 






Hent.addreBB, 




INT 






Entry. points 




ZHT 






Data. point] 


-HI 


conatanta 








VAI. 


data . f i«ld 




IS 


#3F : 


VAL 


data. field. blba 


IS 


£ ; 


VAL 


tag.fiald 




IS 


#C0 : 


VAL 


tag.flald.bit 


a 


IS 


2 ■ 


VAi 


fitfiCA^ga 




IS 







VAL 


numbar 




IS 


1 




VAL 


operat* 




IS 


2 




VAL 


prefix 




IS 


3 





VAX. 
VAL 
VAL 
VAL 

VAL 
VAL 

VAL 
VAL 

VAL 
VAL 



VAL tag. prefix 
VAL moaaage. length 



load 
paaa 
Open 
operate . opart 

cloae 
oparata. cIoka 

addcesB 
axacuta 

Data . position 
operate . execute 



IS prefix « data. field. blta 
15 60 : 



IS 
IS 
IS BYTE {(operate « data. field. blta] 

\/ open] ; 
IS 3 ; 
IS BYTfi ((operate « data. field. bits) 

\/ cloRe} ; 
IS 
IS 



IS EYEE ({operate « data, field, bits) 
\/ execute] 



VAL operate. data. poation IS BYTE ((operate « data. field. blta) 

\/ Data.poaltion) ; 

VAL code . load IS 7 : 

VAL operate. code. load IS BYTE ((operate « data. field. bits) 

\/ code. load} : 

VAL coda . address IS 8 : 

VMi operate. code. addresfi IS BYTE ({operate « data. field. bite) 

\/ COde.addreBs) ; 

VIL data.loici IS 9 : 

VAL operate. data. loacl IS BYTE ( (operate « data, field. bite) 

V/ data. load) : 

VAL data.addreaa IS 10 : 

VAL operate. data, addret* IS BYrE ((operate « data. field, bits) 

\/ data.addra£A) 

VAL Entry. position IS 11 : 

VAL operate. entry. position IS BYTE {(operate « data. field. bits) 

\/ Entry. position) : 
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VU BaotBtrap.lo&d IS 12 : 

VJLL Oparittt. bootstrap. load IS BYTZ { (ope rat* « data. fl«ld.blt9) 

\/ aootmtra.p.lo&d) 

VAL Bootstrap . «nd IS 13 : 

VUi Oparat*. bootstrap. And IS BYTE ( (opArata « data. flald. bits) 

\/ BootBtra.p,and} 

— {({ VARIABIiS 

BlfTE command. : 

IHT Bootstrap. dapth, llnka, to.Ioad, laat.addEBBB^ output. link. : 

BCX3L loadinci : 

SE2 

boOtlirJc.in ? command 
HHII2 command <> operate. «xecute 
IHT tag, operand : 
"({( pcocasB cojnmand 
SEQ 

tag lEc {IHT coiDinand) » data, field. bits 
operand :« IINI command] /\ data. field 
IF 

--{({ tag > meflAage 
tag ■ meaaagB 

IHT losd- fttldrftSft ; 
SEQ 
IF 

— {{{ loading 
loading 

load.addresB :- laet.addresa 

laat.addrsaB := load.addresB PLUS opacand 
— Hi pasflng on 
TRUE 

load.addreaB := Buffer. addreEJ 

— {{{ Ke*d to meBcacfa 
IF 

operand <> 

bootllnk.ln ? [memory FAOH load.addreES FDA operand] 
TRtJE 

SKIP 
--{{{ aend neesage to outputs 

SEQ 1 - Q FOK 4 
IF 

(linka.to.load /\ <1 « i) ) <> 
SEQ 

llnkB [i ] ! command 
IF 

operand <> 

11ci]cb[1] ! [memory FK.OH load. address FOR operand] 
IRDE 
SKIP 
TRUE 
SKIP 
— ({{ tag ■ op*rate 
tag •■ operate 
IF 

--"{{i operand * load 
oparand - load 
SEQ 

loading :> TRUE 
links. to. load :- 

— Hi operand > data, load 
operand ■* data. load 

SEQ 

loading :^ TRUE 
linXB.to.load :« 
<■-{({ operand = Code, load 
opftcand - codA.load 
SEQ 
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loading '." rROE 

llnk,£. to. load :> 
— {{{ opar^nd = pass 
opecajid — pA&a 

loading := PALSE 
linlca.to.lcad :- 
--{{{ opazand ■ opAn 
operand ■ op«n 
INT depth : 
SEQ 

dflptb := 1 
WHILE depth <> 

bootllnk.in ? commcad 
IF 

command > opara.ta. op«n 

depth :=" depth + 1 
comEiand = Dpara.t*. cloea 

depth := depth - 1 
TRUE 
SKIP 

dapth <> 

links [output .linX] 1 cortdaand 
TRQ2 
SKIP 
— {({ oparand » addr*BA 
operand = addxaflB 

— {(( read in load offaet 

BOOL mare r 

SEg 

last , addr« sb :^ 
nior* :- TRUE 
WHILE maim 
SZQ 

laBt,«4dr4Be :■ laat.addr«flB « data. field. bit* 
bodtlink.ln ? command 
laat.addxABB ;■ laflt.addcee* PLDS 

((IMT command) /\ dat4. field) 

more :■• (IHT contmand) >- t«g. prefix 
— (n entiy jiddre** 
taext .addrea* :> laat . addresa 
operand - Data.paaitlon 
SEQ 

— {[{ read in data position offset 

BOOL more : 

S£Q 

Data. point !^ 
looze :« IKUE 
HHII£ more 
S£0 

Data. point :> Data. point « data. field. bita 

bOotLink.in ? comnand 

Data. point ;- D«t«. point PLUS 

((INT cojcmand) /\ data. field) 

more :> (IHI command) >- tag. prefix 
operand « ELntry.poaitlon 
SEQ 

— {^( read in data position offset 

BOOL mora : 

SBQ 

Entry. point :" 
more := TRUE 
WHI'LK mora 

Entry. p*iiit :- Entry. point « data, field. bite 

72TDS276 02 March 1991 



F.3 The INMOS Network Loader 219 



bo&tllnk.in ? cormcLind 

Entry. point l" Entry. point PLUS 

{(INI comdiAnd) /\ data, field) 

morA := {IHT commAnd) >« tag.prafix 

— {({ en-try addze«s 
opacand > cDda.addrAss 

— (U r«ad in load offset 
BOOL mors : 

last. address :« 
m0r« :- TRDE 
HHILE more 
SEQ 

laet.addraaa :> last.addrasB « data.field.blta 
bootlink. in ? conmand 
last.addre&B :^ laBt.addraGB PLDS 

((IHI codunand] /\ data, field) 

more :> (INT coiDmand) >» ta^.f-reflx 
Entry. point r^ Iast.addr«BB 
operand ■■ data.addrass 
SEQ 

— Hi read In load off sat 
BOOL iiLore : 

SEQ 

laet.addrtsa :« o 
mora r^c TRUE 
VRlLS, mora 

laat.addr*** :^ laat.addraaa « data. field. bit ■ 
bootllnk^in 7 cooaLand 
l.aat.addr«aa :> lact.ad4r*aa PLUS 

({INI coofiiand} /\ data, field) 

more :™ (IHC comniand) >•" tag^.pCfifix 
— {{( antry addr*pa 
Data .point :- lafit.addraaa 
oparand = Bootstrap. load 
TUT load. address : 
IMT Bootstrap. length : 
BOOL more : 

Boot strap. depth :» 

Boot strap. longtb :« 

load. address := Buffer . address 

mora :>: TRtTE 

bootlinX . in ? consaand 

more :^ (IHT command] >= data. field 

vnill2. more 

Bootstrap. depth :■ Bootstrap. depth PLUS 1 
SEQ i - FOR 4 
IF 

(llnXs^tD.load /\ (1 « 1]) <> 

links [i] 1 command 
TRQE 
SKIP 
bootlink.in ? coimaand 
more :■ (IMT cocmiand) >•* data. field 

operand ::■- (INI coiimand) /\ data, field 

IF 

Bootatrap. depth > D 

— Hi read in maasa^* 
SEQ 
IF 
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■op* rand <> 

bootllnX.ln ? [mamOry PROM load.addxftSB FOR opttcand] 
TRUE 
SKIP 
— {{i tand nwBXAga to outputs 
SBQ 1 > FOR i 
IF 

<lini.«.to.lo*d /\ (1 « 1)1 <> 
SEg 

llnka [i] ! coranianci 
IP 

Opecand <> Q 

llnlc*[l] 1 [rasmciry fROH load.addro«B 
FOR op«raivJ] 
TRCIE 
SKIP 
TRUE 
SKXE 
TRUE 

mora :- TRUE 

-- The ciaxt procasaorfB] ar« to be bootad M! — 

— so buiid a bootilal* p-acket and output down link -- 

WHILE mors 
SEQ 

boatllnlc.ln ? [in^mory FROM load.addEAss FOR operand] 

load.addr^eB :> load.addzasa PLUS operand 

Boot Btrap. length := Bootstrap. length PLCS operand 

bootlink . in ? command 

'"' Stop jTulldlng when a propar coiQUtAnd 

— is racaivAd This ehould ba whan ■ 

-- 'Bootstrap. and' Is rac4ivad 

moE« ;- (IHI Gommand} < data. field 

operand :« (INT cc-mmAnd) /\ data.fiald 

SZQ i - FOR 4 
IF 

(llnka.to.load /\ (1 « i) ) <> 
EE.Q 

linlcB[i] I {BYTE Bootstrap, len^h] 
IF 

BoDtBtcap.langtb <> 

LinKS[l] ! fmaoiory FROM Buffer, address 
FOR Bootstrap. length] 
TBUB 
SKIP 
TROE 
SKIB 
operand j* Bootstrap. end 
5EQ 

SEQ 11-0 FOR Bootatrap.d«pth 
SEQ 

— Pass on all the other bootatrap and* 
boot link, in ? conmiand 
SEQ 1 > D FOR 4 
IF 

UlnkB.to.load /\ (1 « 1}J <> 

links [1] t CDmmand 
TRUE 
SKXe 
Bootstrap. dapth :' 

--{{{ tag ■ nuinber 
TRUE 

output. I ink :■ operand 

links, to. load :- linJts. to.load \/ (1 « output, link) 
bootlinX.in ? COnmiSnd 
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G.1 introduction 

This appendix describes the format of ITERM files; it is included for people who 
need to write their own ITERM because they are using terminals that are not 
supported by the standard ITERM file supplied with the toolset. You may of 
course wish to tailor a standard ITERM to suit your own needs. 

ITERMs are ASCII text files that describe the control sequences required to 
drive terminals. Screen oriented applications that use ITERM files are terminal 
independent. 

ITERM files are similar in function to the UNIX termcap database and describe 
input from, as well as output to, the terminal. They allow applications that use 
function keys to be terminal independent and configurable. 

Within the toolset, the ITERM file is only used by the debugger tool idebug 
and the T425 simulator tool isiin. 



G.2 The structure of an ITERM file 

An ITERM file consists of three sections. These are the host, screen and key- 
board sections. Sections are introduced by a line beginning with the section 
letters 'H', 'S' or 'K'. Case is unimportant and the rest of the line is ignored. Sec- 
tions consist of a number of lines beginning with a digit. A section is terminated 
by a line beginning with the letter 'E'. The host section must appear first; other 
sections may appear in any order in the file. Sections must be separated by at 
least one blank line. 

The syntax of the lines that make up the body of a section is best described in 
an example: 

3:34, 56, 23, 7, comments 

Each line starts with the Index number followed by a colon and a list of numbers 
separated by commas. Each line is terminated by a full stop ('/) and anything 
following it is treated as a comment. Spaces are not allowed in the data siring 
and an entry cannot be split across more than one line. 

Comment lines, beginning with tlie character '#'. may be placed anywhere in an 
ITERM file. Extra blank lines in the file are ignored. 
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The index numbers in each section correspond to an agreed meaning for the 
data. In the tollowing sections the meaning of the data in each of the three 
sections is described in detail. 

G.3 The host definitions 

G.3.1 ITERM version 

This item identifies an ITERM file by version. It provides some protection against 
incompatible future upgrades. 

e.g. 1:2. 

G.3.2 Screen size 

This itenfi allows applications to find out the size of the terminal at startup time. 
The data items are the number of columns and rows, in that order, available on 
the current terminal. 

e.g. 2:80,25. 

Screen locations should be numbered irom 0, by the application. Terminals 
which use addressing from 1, 1 can be compensated for in the definition of goto 
X.Y, 



G.4 The screen definitions 

The lists of values in the screen section represent control codes that perform 
certain operations; the data values are ASCII codes to send to the display device. 

ITERM version 2 defines the indices given in table G.I. These definitions are 
used in the example ITERM file; for a complete listing of the file see section G.7. 

For example, an entry like: '8:27, 91,75/ indicates that an application should 
output the ASCII sequence 'ESC [ K' to the terminal output stream to clear to 
end of line. 
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Index 


Screen operation 


Index 


Screen operation 


1 


cursor up 


9 


clear to end of screen 


2 


cursor down 


10 


Insert line 


3 


cursor left 


11 


delete line 


4 


cursor right 


12 


ring bell 


5 


goto X y 


13 


home and clear screen 


6 


insert character 


20 


enhance on (not used) 


7 


delete character at cursor 


21 


enhance off (not used) 


8 


dear to end of line 







Table G.1 ITERM screen operations 
G.4.1 Goto X Y processing 

The entry for 5, 'goto X Y', requires further interpretation by the application. 
A typical entry for *goto X Y' might be: 

5:27,-11,32,-21,32 
The negative numbers relate to the arguments required for X and Y. 

...,~ab, nn,... 

where: a is the argument number (i.e. 1 for X, 2 for Y). 

b controls the data output format. 

If 6=1 output is an ASCII byte (e.g. 33 is output as I). 

If b=2 output is an ASCII number (e.g. 33 is output as 3 3), 

nn is added to the argument before output. 

As a complete example, consider the following ITERM entry in the screen section: 

5:27,91,-22,1,59,-12,1,72. ansi cursor control 

This would instruct an application wishing to move the terminal cursor to X=14, 
Y=8 (relative to 0,0) to output the following bytes to the screen: 

Bytes in decimal: 27 91 57 59 49 53 72 
Bytes in ASCII: ESC [ 9 ; 1 5 H 
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G.5 The keyboard definitions 

Each index represents a single keyboard operation. The data specified after 
each index defines the keystroke associated with that operation. 

Multiple entries for the same index indicate alternative keystrokes for the opera- 
tion. 

ITERM version 2 defines the indices given in table G.2. These definitions are 
used in the example ITERM file; for a complete listing of the file see section G.7. 



Index 


Function 


Index 


Function 


2 


delete character 


39 


goto line 


6 


cursor up 


40 


backtrace 


7 


cursor down 


41 


inspect 


8 


cursor left 


42 


channel 


9 


cursor right 


43 


top 


12 


delete line 


44 


retrace 


14 


start of line 


45 


relocate 


15 


end of Jine 


46 


Info 


18 


line up 


47 


modify 


19 


line down 


48 


resume 


20 


page up 


49 


monitor 


21 


page down 


50 


word left 


26 


enter file 


51 


word right 


27 


exit file 


55 


top of fife 


2B 


refresh 


56 


end of file 


29 


change file 


62 


toggle hex 


31 


finish 


65 


continue from 


34 


help 


66 


toggle breakpoint 


36 


get address 


67 


search 



Table G.2 ITERM key operations 
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G.6 Setting up the iTERM environment variable 

To use an ITERM the application has to find and read the file. An environment 
variabie (or iogical name on VMS) calied ITERM should be set up with the 
pathname of the file as its value. For example, under MS-DOS the command 
wouid be: 

C:\> set ITERM=C;\rTOOLS\TOOLS\PCBANSr.ITM 

Under UNIX you would set an environment variable. For example, the command 
for csh users might be: 

% setienv ITERM ~/.iterm 
Under VMS you would define a logical name. For example: 

$ DEFINE ITERM SYS$LOGIN: VTIOO . ITM 

For more details about setting environment variables see the Delivery Manual 
that accompanies the release. 
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G.7 An example ITERM 

This is the toolset ITERM file for the fBM PC using the ANSI screen driver. 



# „ 

» 

# IBM PC (BANSX) ITERM data file (derived from TDS3 ITERM) 

# Support for idebug and isira 

# IDEBUG version for BANSI . SYS driver: 

# Special care needed on screen codes 6, 7, 9, 10, 11 
# 

# VI. 1 - 10 July 90 (KH) Updated idebug and isim support 
# 

# 



host section 

1:2. 

2:80,25. 

end of host section 

# screen control characters 



version ■ 
screen size 



screen section 










# 








DEBUGGER 


SIMULATOR _ 


1:27,91,65. 










cursor up 


2:27,91,66. 










cursor down 


3:27,91,68. 








cursor left 


cursor left 


4:27,91,67. 










cursor right 


5:27,91,-22, 


1, 


59 


,-12,1,72. 


goto X Y 


goto X y 


6:27,91,64. 








insert char 


insert char 


7:27,91,80. 








delete char 


delete char 


8:27,91,75. 








clear to eol 


clear to eol 


9:27,91,74. 








clear to eos 


clear to eos 


10:27,91,76. 








insert line 


insert line 


11:27,91,77. 








delete line 


delete line 


12:7. 








bell 


bell 


13:27,91,50, 


74 


. 




clear screen 


clear screen 


end of screen 


set 


2tion 






keyboard section 








« 
# 
2:8. 




KEY 


DEBUGGER 


SIMULATOR 




# 


BACKSPACE 


del char 




6:0,72. 




# 


UP 


cursor up 


cursor up 


7:0,80. 




# 


DOWN 


cursor down 


cursor down 


8:0,75. 




# 


LEFT 


cursor left 


cursor left 


9:0,77. 




# 


RIGHT 


cursor right 


cursor right 


12:0,110. 




# 


ALT P7 


delete line 
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12:21. 




CTRL U 


delete lins 




12:24. 




CTRL X 


delete line 




14:0,65. 




F7 


start of line 


start of line 


15:0,66. 




F8 


end of line 


end of line 


18:0,67, 




F9 


line up 




19:0,68. 




FIO 


line down 




20:0,112. 




ALT F9 


page up 


page up 


21:0,113, 




ALT FIO 


page down 


page down 


26:0,71. 




NUM 7 


enter file 




27:0,73. 




NUM 9 


exit file 




28:27. 




ESC 


refresh 


refresh 


29:0,87. 




SHIFT F4 


change file 




31:0,117. 




CTRL NUM 1 


finish 




34:0,59. 




Fl 


help 


help 


36:0,63. 




F5 


get address 




39:0,64. 




F6 


goto line 




40:0,129. 




ALT 


backtrace 




41:0,120. 




ALT 1 


inspect 




42:0,121. 




ALT 2 


channel 




43:0,122. 




ALT 3 


top 




44:0,123. 




ALT 4 


retrace 




45:0,124. 




ALT 5 


relocate 




46:0,125. 




ALT 6 


info 




47:0,126. 




ALT 7 


modify 




48:0,127. 




ALT 8 


resume 




49:0,128. 




ALT 9 


monitor 




50:0,90. 




SHIFT F7 


word left 




50:6. 




CTRL F 


word left 




50:0,115. 




CTRL NUM 4 


word left 




51:0,91. 




SHIFT F8 


word right 




51:7. 




CTRL G 


word right 




51:0,116, 




CTRL NUM 6 


word right 




55:0,92. 




SHIFT F9 


top of file 




55:20. 




CTRL T 


top of file 




56:0,93. 




SHIFT FIO 


end of file 




56:2. 




CTRL B 


end of file 




62:0, lOB. 




ALT F5 


toggle hex 




65:0,105. 




ALT F2 


continue from 




66:0,99. 




CTRL F6 


toggle break 




67:0,88. 




SHIFT F5 


search 





end Of keyboard stuff 

# idebug key that isn't really part of iterra but its here 
all the same I 

# 

# INTERRUPT CTRL A ~ IDEBUG 

# THAT'S ALL FOLKS 
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H Host file server 
protocol 



This appendix describes the protocol of the host file server iserver. 



H.I The host file server iserver 

The host file server iserver is implemented in C which facilitates porting to 
other machines. This provides an easy method of porting the toolset (or pro- 
grams written under the toolset) to new hosts. The server can, at a cost to 
portability, be extended to accomodate new host features. 

The source of the server and of the libraries used to communicate with the server 
Is supplied with the toolset. 



H.2 The server protocol 

Every communication to and from the sen/er is a packet consisting of a counted 
array of bytes. The count gives the length of the message and is sent in the first 
two bytes of the packet as a signed 16 bit number. The structure of a sen/er 
packet is illustrated in figure H.1. 

This protocol has been given the name SP, and is defined in Occam as follows: 

PROTOCOL SP IS IKT16; ; []BYTE : 

H.2.1 Packet size 

There is a maximum packet size of 1024 bytes and a minimum packet size of 8 
bytes in the to-server direction (i.e. a minimum message length of 6 bytes). The 
server may take advantage of this knowledge. 

The packet size must always be an even number of bytes. If the number of 



bO 


b1 


message of length bO 4- (256 * b1) 



Figure H.1 SP protocol packet 
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bytes is odd a dummy byte is added to the end of the packet and the packet 
byte count rounded up by one. 

The hostio library contains routines that ensure that the size restrictions are met 
when sending a packet to the sen/er (see section H.3). 

H.2.2 Prolocof operation 

Every request sent to the server receives a reply of the same protocol, in strict 
sequence, and no further requests are accepted until the reply has been sent. 

Unless otherwise stated all integer types used by the protocol are signed. Num- 
bers are transmitted as sequences of bytes (2 bytes for 16 bit numbers, 4 bytes 
for 32 bit numbers) with the least significant byte first. Negative integers are 
represented in 2s complement. Strings and other variable length blocks are 
introduced by a 16 bit signed count. 

All server calls return a result byte as the first item in the return packet. If the 
operation succeeds the result byte is zero and if the operation fails the result 
byte is non-zero. The result is one {1) in the special case where the operation 
fails because the function is not implemented^ Jf the result is non-zero, some or 
all of the return values may not be present, resulting in a smaller return packet 
than if the call was successful. 



H.3 The server libraries 

The hostio library hostio . lib contains ad the routines provided in the toolset 
for communicating with the server. It contains a set of basic routines, hidden 
from the user, from which the more complex user visible routines are built. 

A naming convention has been adopted for the sen/er libraries. The basic library 
routines use the server protocol directly and map directly to server functions. 
These have the prefix 'sp.'. Routines which use the basic routines and are 
visible to the user have the prefix 'so.'. The 'so.' routines documented in this 
manual use underlying 'sp/ routines, and in some cases the mapping is one 
to one. 

The source of the hostio library is provided with the toolset and serves as an 
example of how to use the SP protocol. 

^Result values between 2 and 127 are defined to have particular meanings by OCCam 
server libraries. Resujt values of 128 or above are specific to the implementation of a server. 
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If you add your own libraries for server functions you are recommended to keep 
to the naming convention. 

There are two 'sp/ library routines included to help you extend the set of 
available routines. These are sp. send, packet and sp. receive, packet. 
These are described below. 

sp . send . packet 

PROC sp. send. packet (CHAN OF SP ts, 

VAL [IBYTE packet, 
BOOL error) 

This procedure sends a packet on the channel ts, provided that it meets 
the requirements for a SP protocol packet. If the requirements are not 
met then the packet is not sent and error is set to true. 

sp . receive . packet 

PROC sp. receive. packet (CHAN OF SP' fs, 

INT16 length, 
[JBYTE packet, 
BOOL error) 

This procedure receives a packet on the channel fa. The received packet 
is in the first length bytes of packet. The value error is set to true 
if the size of the packet received exceeds sp .max . packet . data . size; 
otherwise it is false. 



H.3.1 Problems with packet size 

The maximum packet size which may be handled by iserver is 1024, this 
causes a potential problem, however, for some routines in hostio.iib. This 
is because the hostio routines have a maximum packet size of 512 bytes. The 
hostio routines which may be affected are: 

• so.getenv 

• so . commandline 

• so . f error 

• so. buffer 

• so. overlapped. buffer 
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• so. multiplexor 

• so. overlapped. multiplexor 

• so. pri. multiplexor 

• so. overlapped. pri .multiplexor 

Should any of these routines receive a packet larger than 512 bytes» they will 
act as invalid processes. 

Care should be taken that the multiplexor and buffer routines listed above are 
not used by any routines which are likely to exceed the 512 byte limit. 



H,4 Porting the server 

In order to port the iserver to a new machine you must have a C compiler 
for that machine. A number of Makefiles that can assist with porting to a new 
machine are supplied in the toolset 'source' subdirectory. 

The hostio library expects all the functions described below to be provided by 
iserver. 



H.5 Defined protocol 

The functions provided by the iserver are split into three groups: 

1 File commands, for interacting with files 

2 Host commands, for interacting with the host 

3 Server commands, for interacting with the server. 

In the descriptions that follow, the arguments and results of server calls are listed 
in the order that they appear in the data part of the packet. The size of a packet 
is the aggregated size of all the items in the packet, rounded up to an even 
number of bytes. OCCam types are used to define data items within the packet. 

H,5.1 Reserved values 

INMOS reserves the following values for its own use: 
• Function tags in the range to 127 inclusive. 
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• Result values in the range to 255 inclusive. 

• Stream identifiers 0, 1 and 2. 

Some commands may return particular values, which may be reserved. The 
range of reserved values is given with each command as appropriate. 

H.5.2 File commands 

Open files are identified with 32 bit descriptors. There are three predefined open 
files: 

- standard input 

1 - standard output 

2 - standard error 

If one of these is closed then It may not be reopened. 

Fopen - Open a file 

Synopsis: Streamid = Fopen ( Namer Type, Mode ) 

To server: BYTE Tag =10 

INT16 ; : [ ] BYTE Name 

BYTE Type = 1 or 2 

BYTE Mode = 1 ... 6 

From seirver: BYTE Result 

INT32 Streamid 

Fopen opens the file Name and, if successful, returns a stream identifier 
Streamid. 

Type can take one of two possible values: 

1 Binary. The file will contain raw binary bytes. 

2 Text. The file will be stored as text records. Text files are host- 
specified. 

Mode can have 6 possible values: 

1 Open an existing file for input. 
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2 Create a new file, or truncate an existing one, for output. 

3 Create a new file, or append to an existing one, for output. 

4 Open an existing file for update (both reading and writing), starling 
at the beginning of the file. 

5 Create a new file, or truncate an existing one, for update. 

6 Create a new file, of append to an existing one, for update. 

When a file is opened for update (one of the last three modes above) then 
the resulting stream may be used for input or output. There are restric- 
tions, however. An output operation may not foIJow an input operation 
without an intervening Fseek, Ftell or Fllush operation. 

The number of streams that may be open at one time is host-specified, 
but will not be less than eight (Including the three predefines). 



Fclose - Close a file 






Synopsis ; 


Fclose ( 


Streamld ) 


To server: 


BYTE 


Tag = 11 




INT32 


Streamid 


From server: 


BYTE 


Result 



Fclose closes a stream streamid which should be open for input or out- 
put. Fclose flushes any unwritten data and discards any unread buffered 
input before closing the stream. 
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Fread - Read a block of data 

Synopsis: Data = Fread( Streamld, Count ) 

To server: BYTE Tag = 12 

INT32 Streamid 

INT 16 Count 

From server: BYTE Result 

INT16: : []BYTE Data 

This function is obsotete. See the definition of FGetBIock for its 
replacement. 

Fread reads Count bytes of binary data Irom the specified stream. Input 
stops when the specified number of bytes are read, or the end of file is 
reached, or an error occurs. If Count is less than one then no input is 
done. The stream is left positioned immediately after the data read. !f 
an error occurs the stream position is undefined. 

Result is always zero. The actual number of bytes returned may be 
less than requested and Feof and Ferror should be used to check for 
status. 
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Fwrite - Write a block of data 

Synopsis: Written = Fwrite ( Streamld, Data ) 

To server: BYTE Tag = 13 

INT32 Streamid 

INT16: : []BYTE Data 

From server: BYTE Result 

INT16 Written 

This function is obsolete. See the definition of FPutBlock for its 
replacement. 

Fwrite writes a given number of bytes of binary data to the specified 
stream, which should be open for output. If the length of Data is tess 
than zero then no output is done. The position of the stream is advanced 
by the number of bytes actually written. If an error occurs then the re- 
sulting position if undefined. 

Fwrite returns the number of bytes actually output in Written, Result 
is always zero. The actual number of bytes returned may be [ess than 
requested and Feof and Ferror should be used to check for status. 

If the streamid is 1 (standard output) then the write Is automatically 
flushed. 

Fgets - Read a line 

Synopsis; Data = Fgets ( Streamid, Count ) 

To server; BYTE Tag - 14 

1NT32 Streamid 

INT 16 Count 

From server: BYTE Result 

INTl 6 : : [ J BYTE Data 



Fgets reads a line from a stream which must be open for input. Charac- 
ters are read untiJ end of file is reached, a newline character is seen or 
the number of characters read is not less than Count. 

If the input is terminated because a newline is seen then the newline 
sequence is not included in the returned array. 
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If end o1 file is encountefed and nothing has been read from the stream 
then Fgets fails. 

Fputs - Write a line 

Synopsis: Fputs ( Streamid, String ) 

To server: BYTE Tag = 15 

INT32 Streamid 

INT16: : I] BYTE String 

From server: BYTE Result 



Fputs writes a line of text to a stream which must be open for output. 
The host-specified convention for newline will be appended to the line 
and output to the file. The maximum line length is host-specified. 



Fflush - Flush a stream 

Synopsis: Fflush ( Streamid ) 



To server: 


BYTE 


Tag = 16 




INT32 


Streamid 


From server: 


BYTE 


Result 



Fflush flushes the specified stream, which should be open for output. Any 
internally buffered data is written to the destination device. The stream 
remains open. 
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Fseek - Set position in a file 

Synopsis: Fseek ( Streamid, Offset, Origin ) 



To server: 


BYTE 


Tag = 17 




INT32 


Streamid 




INT32 


Offset 




INT32 


Origin 



From server: BYTE Result 

Fseek sets the file position for the specified stream. A subsequent read 
or write wilt access data at the new position. 

For a binary file the new position will be Offset characters from Origin 
which may take one of three values: 

1 Set, the beginning of the file 

2 Current, the current position in the file 

3 End, the end of the file. 

For a text stream, Offset must be zero or a value returned by Ftell. ff 
the latter is used then Origin must be set to 1 . 

Ftell - Find out position in a file 

Synopsis: Position = Ftell ( Streamid ) 

To server; BYTE Tag = IS 

INT32 Streamid 

From server: BYTE Result 

IMT32 Position 

Ftell returns the current file position for streamid. 
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Feof - Test for end of file 

Synopsis: Feof( Streamid ) 



To server: 


BYTE 


Tag = 19 




INT32 


Streamid 


From server: 


BYTE 


Result 



Feof succeeds if the end of f][e indicator for streamid is set. 

Ferror - Get file error status 

Synopsis: ErrorNo, Message = Ferror (Streamid) 

To server: BYTE Tag = 20 

INT32 Streamid 

From server: BYTE Result 

INT32 ErrorNo 

INT16: : []BYTE Message 



Ferror succeeds if the error indicator for streamid is set. If it is, Fer- 
ror returns a host-defined error number and a (possibiy null) message 
corresponding to the last file error on the specified stream. 



Remove - Delete a file 

Synopsis : Remove ( Name ) 

To server: BYTE Tag =21 

INT16: : []BYTE Name 

From server: BYTE Result 

Remove deletes the named file. 
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Rename - Rename a file 

Synopsis: Rename { OldName, NewName ) 

To server: BYTE Tag = 22 

INTl 6 : ; n BYTE OldName 
INTl 6 : ; [ ] BYTE NewName 

From server: BYTE Result 

RBname changes the name of an existing file OldName to NewName. 

FGetBlock - Read a block of data and return status 

Synopsis: Data, Result - FG©tBloclc(Streainld, Count) 

To server; BYTE Tag = 23 

INT32 Streamid 

INTl 6 Count 

From server; BYTE Result 

INTl 6: : I] BYTE Data 

FGetBlock reads Count bytes of binary data from the specified stream. 
Input stops when the specified number of bytes are read, or the end of 
file is reached, or an error occurs. If Count is less than one then no 
input is done. The stream Is left positioned immediately after the data 
read. If an error occurs the stream position is undefined. 

The actual number of bytes returned may be less than requested. In the 
case of Result indicating a failure Feof and Ferror should be used to 
determine the cause of the error. 

This function is preferred over the Fread function, which should no longer 
be used. 
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FPutBlock - Write a blocl( of data and return status 

Synopsis: Written, Result = FPutBlock (Strearald, Data) 

To server; BYTE Tag = 24 

INT32 Streamld 

INT16; ; I ] BYTE Data 

From server: BYTE Result 

INT16 Written 



FPutBlock writes a given number of bytes of binary data to the speci- 
fied stream, which should be open for output. If the length of Data is 
less than one then no output is done. The position of the stream is ad- 
vanced by the number of bytes actually written. If an error occurs then 
the resulting position if undefined. 

FPutBlock returns the number of bytes actually output in Written. The 
actual number of bytes returned may be less than requested and Feof 
and Ferror should be used to check for status. 

If the Streamld is 1 (standard output) then the write is automatically 
flushed. 

This function is preferred over the Fwrite function, which should no longer 
be used. 



H.5.3 Host commands 

Getkey - Get a keystroke 

Synopsis: Key = GetKeyO 

To server: BYTE Tag = 30 

From server: BYTE Result 

BYTE Key 



GetKey gets a single character from the keyboard. The keystroke is 
waited on indefinitely and will not be echoed. The effect on any buffered 
data in the standard input stream is host-defined. 



72TDS276 02 March 1991 



242 H Host file server protocol 

Pollkey - Test for a key 

Synopsis; Key = PollKeyO 

To server: BYTE Tag = 31 

From server: BYTE Result 

BYTE Key 



PoSIKey gets a single character from the keyboard. If a keystroke is not 
available then PollKey returns immediately with a non-zero result If a 
keystroke is available it will not be echoed. The effect on any buffered 
data in the standard input stream is host-defined. 



Getenv - Get environment variable 

Synopsis; Value = Getenv ( Name ) 

To server: BYTE Tag = 32 

INT16: : []BYTE Name 

From server: BYTE Result 

INT16 : : [ ] BYTE Value 



Getenv returns a host-defined environment string ior Name. If Name is 
undefined then Result will be non-zero. If the resultant environment 
string for Name is longer than the space available in the packet buffer, 
then it will be truncated. 



Time - Get the time of day 

Synopsis: LocalTime, UTCTime = Time() 

To server: BYTE Tag = 33 

From server: BYTE Result 

INT32 LocalTime 

INT32 UTCTime 

Time returns the [ocal time and Coordinated Universal Time if it is avail- 
able. Both times are expressed as the number of seconds that have 
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elapsed since midnight on 1st January, 1970. if UTC time is unavail- 
able then it will have a value of zero. The times are given as unsigned 
INT32S. 

System - Run a commanci 

Synopsis: Status = System ( Command ) 

To server: BYTE Tag =34 

INTl 6 ; : [ ] BYTE Command 

From server; BYTE Result 

INT32 Status 



System passes the string Command to the host command processor for 
execution. If Command is zero length then System will succeed if there 
is a command processor. If Command is not null then Status is the 
return value of the command, which is host-defined. 



IH.S.4 Server connmands 

Exit - Terininate the server 

Synopsis; Exit ( Status ) 



To server; 


BYTE 


Tag = 35 




INT32 


Status 


From server; 


BYTE 


Result 



Exit terminates the server, which exits returning status to its caller. 

If Status has the special value 999999999 then the server will terminate 
with a host-specific 'success' result. 

If Status has the special value -999999999 then the server will termi- 
nate with a host-specific laiture' result. 
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CommandUne - Retrieve the server command line 

Synopsis; String - CoininandLine{ All ) 

To server: BYTE Tag =40 

BYTE All 

From server: BYTE Result 

INTl 6 : : [ ] BYTE String 



CommandLine returns the command line passed to the server on invo- 
cation. On certain operating systems it is possible to quote arguments 
on the command line. The quotes themselves have been removed by 
the time the arguments are passed on to the server. When building 
the command line to pass on to the application the server replaces the 
quotes- 

If All is zero the returned string is the command line, with options and 
their arguments that the server recognised at startup removed, as well 
as the server command. 

If All is non-zero then the string returned is the entire command vector 
as passed to the server on startup, including the name of the server 
command itself. 



Core - Read peeked memory 

Synopsis Data = Core ( Offset, Length ) 

I 

I 



To server; 


BYTE 


Tag = 41 




INT32 


Offset 




INTl 6 


Length 



From server: BYTE Result 

INTl 6 : ; [ ] BYTE Core 



Core returns the contents of the root transputer's memory, as peeked 
from the transputer when the server was invoked with the analyse option. 

Core fails if Offset Is larger than the amount of memory peeked (rom 
the transputer or if the transputer was not analysed. 

If Offset + Length is larger than the total amount of memory that 
was peeked then as many bytes as are avaiiable from the given offset 
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are returned. 
Version - Find out about the server 

Synopsis: Id = Version () 

To server: BYTE Tag = 42 



From server; 


BYTE 


Result 




BYTE 


Version 




BYTE 


Host 




BYTE 


OS 




BYTE 


Board 



Versiori returns lour bytes containing identification information about the 
server and the liost it is running on. 

If any of tiie bytes has the value then that information is not available. 

Version identifies the server version. The byte value should be divided 
by ten to yield the version number. 

Host identifies the host machine and can be any of the following: 

1 PC 

2 NEC-PC 

3 VAX 

4 Sun 3 

5 370 Architecture 

6 Sun 4 

7 Sun 3861 

8 Apollo 

OS identifies the host environment and can be any of the following: 

1 DOS 

2 Helios 

3 VMS 
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4 SunOS 

5 CMS 

Board identifies the interface board and can be any of the following: 

1 B004 

2 BOOS 

3 BOlO 

4 B011 

5 8014 

6 DRX-11 
7QT0 

8 B015 

9 CAT 

10 B016 

11 UDPlink 

Values of Host, OS and Board from to 127, inclusive, are reserved for use 
by INMOS. 
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Alias check A program compilation check that ensures that names are unique 
within a given scope. 

Analyse To assert a signal to a transputer forcing it to halt at the nextdeschedul- 
ing point, to allow the state of the processor to be read. In the conte)(t 
of 'analysing a network', to analyse all processors in the network. 

Also refers to one of the system control functions on transputers and the 
pin on which the function is asserted. 



Backtrace Within the debugger and simulator tools, to move from a position 
within a procedure or function body to the call of that procedure or func- 
tion. 

Bootable code Self-starting program code, that can be loaded onto a transputer 
or transputer network down a transputer link and run. Bootable code is 
produced by icollect from linked units (single transputer programs) 
or configuration binary files (configured programs). 

Bootstrap A transputer program, loaded from a ROM or over a link after the 
transputer has been reset or analysed, which Initialises the processor 
and loads a program lor execution (which may be another loader). 



Compiler library A group of Occam library routines that are used by the com- 
piler to implement extended arithmetic and transputer system operations. 

Configuration The association of components of a program with a set of physi- 
cal resources. Used in this manual to refer to the specific case of allocat- 
ing software processes to processors in a network, and channels to links 
between processors. The term is also used, depending on the context, 
to describe the act of deciding on these allocations for a program, the 
configuration code which describes such a set of allocations, and the act 
of applying the configurer to a network description. 

Configurer The tool which assigns processes and channels on a specified con- 
figuration of transputers. The output from the tool is a configuration binary 
file for input to icollect. 
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Deadlock A state in which on© or more concurrent processes can no longer 
proceed because of a communication interdependency. 

Error mode The compilation mode of a program that detenmines what happens 
when a program error (such as an array bounds violation) occurs. A 
program compiled using the toolset may be compiled in one of three 
error modes: HALT, STOP, or UNIVERSAL 

Error signal In the transputer, an external signal used to indicate that an error 
has occurred in a running program. Atso refers to one of the system 
control functions on transputers. Error signals can be OR-ed together 
on transputer boards to indicate an error has occurred in one of the 
transputers in the network. 

Extended data types Occam data types INT16, INT32, INT64, REAL32 
and ke:al64. 



Hard channels Channels which are mapped onto links between processors in 
a transputer network (cf. Soft channels). 

Host The computer which is running the toolset host file server and providing 
the filing system and terminal i/o. 

Host file server A file server which provides access to the filing system and 
terminal i/o of a host operating system^ which may be used when running 
standalone programs. The toolset host file server is distinct from that 
used to run the Transputer Development System (TDS). 



Include file A file containing source code which is incorporated into a program 
using the #include directive. 



Library A collection of separately compiled procedures or functions, created by 
the toolset librarian iiibr, which may be shared between parts of a 
program or between different programs. 

Library build file Afilecontainmgafistof input files for the librarian too! ilibr. 
Each file forms a separately loadable module in the library. Library build 
files must have the , Ibb extension. 
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Library usage file A file listing the libraries and separately compiled units used 
by another library. Library usage files must have the . liu extension. 

Link In the context oi transputer hardware, the serial communication link be- 
tween processors. Used as a verb in the context of program compilation, 
to collect together all the code for a program or compilation unit, resolving 
all references and recompiling where necessary, and place the collected 
code into a single file. 

Linker The program or tool which links a program or compilation unit. 

Loader Depending on the context, refers to the part of the host file server which 
loads a transputer network or to a small program which is loaded into 
a transputer, and which then distributes code to other transputers and 
toads a larger program on top of itself. 



Makefile An input file for a Make program, A Makefile contains details of file 
dependencies and directions for rebuilding the object code. Makefiles 
are created for the toolset using imakef . 



Network A set of transputers connected together using links as a connected 
graph, that is, in such a way that there is a path, via links and other 
transputers, from each transputer to every other transputer in the set. 

Newline sequence The sequence of ASCII characters, defined within the host 
file server^ that directs a new line to be started on the terminal display or 
within a file. Defined for the toolset as the sequence 'CR LF'. 



Object code intermediate code between source and bootable files. Object code 
cannot be directly loaded onto a transputer and run. The compiler and 
linker tools generate object code. 



Peek and poke To read and write locations in a transputer's memory, by com- 
munication over a link, while the transputer is waiting for a bootstrap. 

Preamble The part of a transputer loader program that initialises the state of the 
processor. 
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Priority In the transputer, the priofity level at which the currently executing pro- 
cess is being run. INMOS transputers support two levels of priority, known 
as 'high' and 'low'. 

Process Self-contained, independently executable OCCam code. 

Protocol The pattern of communications between two processes, often includ- 
ing communications on more than one channel- When appearing as 
PROTOCOL, refers to a specific communication structure on an OCCann 
channel (see the 'OCCam 2 Reference Manuai'). 



Reset The transputer system initialisation control signal. Also refers to the pin 
on which the signal is asserted. 

Root transputer (or Root processor) The processor in a transputer network 
which is physically connected to the host computer, and through which 
the network is loaded or analysed. 



Separate compilation A self-contained part of a program may be separately 
compiled, so that only those parts of a program which have changed 
since the last compilation need to be recompiled. 

Server A program running in the host computer attached to atransputer network, 
which provides access to the filing system and terminal i/o of the host 
computer. The server can also be used to load the program onto the 
network. 

Soft channels Channels declared and used within a process running on a single 
transputer, (cf. Hard channels). Soft channels are implemented by a 
single word in memory. 

Standard error The host system error handler. Errors directed to standard error 
are displayed in a host-defined way, for example, on the terminal screen. 
For details of how to modify standard error on the system, consult the 
operating system documentation. 

Standard Input The host system input handler. Specifies the standard Input 
device, for example the terminal keyboard or a disk file. For details of 
how to modify standard input on the system, consult the operating system 
documentation. 

Standard output The host system output handler. Specifies the standard output 
device, for example, the terminal screen or a disk file. For details of how 
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to modify standard input on the system, consult the operating system 
documentation. 

Subsystem In transputer board architecture, the combination of the Reset, Anai- 
yse and Error signals which allows the board to control another board on 
its subsystem' port. 



Target transputer The transputer on which the code Is intended to njn. The 
transputer type, or a restricted set of types defined in a transputer class, 
is defined when the program is compiled, using command line options. 



Usage check A compilation check that ensures no variables are shared between 
parallel processes, and that enforces rules about the use of channels as 
unidirectional point-to-point connections. 



Vector space The data space required for the storage of vectors (an'ays) within 
an Occam program. 



Workspace The data space required by an OCCam process; when used in 
contrast to Vector space, refers to the data space required for scalars 
within the process. 
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